// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

using System.Threading;
using System.Threading.Tasks;

namespace Microsoft.CodeAnalysis.Navigation;

/// <summary>
/// Service to allow 3rd party languages to handle navigating to some metadata symbol.  For example, this can allow
/// a language like F# to navigate to its source definition of a symbol that roslyn views as a metadata symbol.
/// </summary>
internal interface ICrossLanguageSymbolNavigationService
{
    /// <summary>
    /// Attempts to get location that can be navigated to for a particular symbol id.  The symbol id format is
    /// defined at: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#id-strings.  Should
    /// return <see langword="null"/> if the 3rd party language cannot navigate to this particular symbol.
    /// </summary>
    /// <param name="assemblyName">The name of the assembly the symbol was defined in. Can be used by the
    /// receiver to quickly filter down to the project/compilation search for the symbol.</param>
    Task<INavigableLocation?> TryGetNavigableLocationAsync(
        string assemblyName, string documentationCommentId, CancellationToken cancellationToken);
}