' 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.
 
Imports System
Imports System.Collections.Generic
Imports System.Diagnostics
Imports System.Globalization
Imports System.IO
Imports System.Text
Imports System.Runtime.InteropServices
Imports System.Threading
Imports Microsoft.CodeAnalysis.Collections
Imports Microsoft.CodeAnalysis.PooledObjects
Imports Microsoft.CodeAnalysis.VisualBasic
Imports Microsoft.CodeAnalysis.VisualBasic.Symbols
Imports Microsoft.CodeAnalysis.VisualBasic.Syntax
 
Namespace Microsoft.CodeAnalysis.VisualBasic
    Partial Public Class VisualBasicCompilation
 
        Partial Friend Class DocumentationCommentCompiler
            Inherits VisualBasicSymbolVisitor
 
            ''' <summary>
            ''' Generates the documentation comment for the type, writes it into 
            ''' the writer
            ''' </summary>
            Public Overrides Sub VisitNamedType(symbol As NamedTypeSymbol)
                Me._cancellationToken.ThrowIfCancellationRequested()
 
                If Not ShouldSkipSymbol(symbol) Then
                    Dim sourceNamedType = TryCast(symbol, SourceNamedTypeSymbol)
                    If sourceNamedType IsNot Nothing Then
                        WriteDocumentationCommentForNamedType(sourceNamedType)
                    End If
 
                    If Not Me._isForSingleSymbol Then
                        For Each member In symbol.GetMembers()
                            Me.Visit(member)
                        Next
                    End If
                End If
            End Sub
 
            Private Sub WriteDocumentationCommentForNamedType(namedType As SourceNamedTypeSymbol)
 
                Dim multipleDocComments = ArrayBuilder(Of DocumentationCommentTriviaSyntax).GetInstance
                Dim maxDocumentationMode As DocumentationMode = DocumentationMode.None
 
                For Each reference In namedType.SyntaxReferences
                    Dim trivia As DocumentationCommentTriviaSyntax =
                        TryGetDocCommentTriviaAndGenerateDiagnostics(reference.GetVisualBasicSyntax(Me._cancellationToken))
 
                    If trivia IsNot Nothing Then
                        multipleDocComments.Add(trivia)
 
                        Dim documentationMode As DocumentationMode = trivia.SyntaxTree.Options.DocumentationMode
                        If maxDocumentationMode < documentationMode Then
                            maxDocumentationMode = documentationMode
                        End If
                    End If
                Next
 
                Dim symbolName As String = GetSymbolName(namedType)
 
                If multipleDocComments.Count > 1 Then
                    ' In case we have multiple documentation comments we should discard 
                    ' all of them with (optionally) reporting all diagnostics 
                    If maxDocumentationMode = DocumentationMode.Diagnose Then
                        For Each trivia In multipleDocComments
                            Me._diagnostics.Add(ERRID.WRN_XMLDocOnAPartialType, trivia.GetLocation(), symbolName)
                        Next
                    End If
                    multipleDocComments.Free()
 
                    ' No further processing of any of the found documentation comments
                    Return
 
                ElseIf multipleDocComments.Count = 0 Then
                    multipleDocComments.Free()
                    Return
                End If
 
                Dim wellKnownElementNodes As New Dictionary(Of WellKnownTag, ArrayBuilder(Of XmlNodeSyntax))
                Dim theOnlyDocumentationCommentTrivia As DocumentationCommentTriviaSyntax = multipleDocComments(0)
                multipleDocComments.Free()
 
                Dim docCommentXml As String = GetDocumentationCommentForSymbol(namedType, theOnlyDocumentationCommentTrivia, wellKnownElementNodes)
 
                ' No further processing
                If docCommentXml Is Nothing Then
                    FreeWellKnownElementNodes(wellKnownElementNodes)
                    Return
                End If
 
                If theOnlyDocumentationCommentTrivia.SyntaxTree.ReportDocumentationCommentDiagnostics OrElse _writer.IsSpecified Then
                    Dim delegateInvoke As MethodSymbol = namedType.DelegateInvokeMethod
 
                    ' Duplicate top-level well known tags
                    ReportWarningsForDuplicatedTags(wellKnownElementNodes)
 
                    ' <exception>
                    ReportIllegalWellKnownTagIfAny(WellKnownTag.Exception, wellKnownElementNodes, symbolName)
 
                    ' <returns>
                    If namedType.TypeKind = TypeKind.Delegate Then
                        If delegateInvoke IsNot Nothing AndAlso delegateInvoke.IsSub Then
                            ReportIllegalWellKnownTagIfAny(WellKnownTag.Returns, wellKnownElementNodes, "delegate sub")
                        End If
                    Else
                        ReportIllegalWellKnownTagIfAny(WellKnownTag.Returns, wellKnownElementNodes, symbolName)
                    End If
 
                    ' <param> & <paramref>
                    If namedType.TypeKind = TypeKind.Delegate Then
                        ReportWarningsForParamAndParamRefTags(wellKnownElementNodes, GetSymbolName(delegateInvoke), delegateInvoke.Parameters)
                    Else
                        ReportIllegalWellKnownTagIfAny(WellKnownTag.Param, wellKnownElementNodes, symbolName)
                        ReportIllegalWellKnownTagIfAny(WellKnownTag.ParamRef, wellKnownElementNodes, symbolName)
                    End If
 
                    ' <value>
                    ReportIllegalWellKnownTagIfAny(WellKnownTag.Value, wellKnownElementNodes, symbolName)
 
                    ' <typeparam> & <typeparamref>
                    If namedType.TypeKind = TypeKind.Enum Then
                        ReportIllegalWellKnownTagIfAny(WellKnownTag.TypeParam, wellKnownElementNodes, symbolName)
                        ' <typeparamref>
                        ReportWarningsForTypeParamRefTags(wellKnownElementNodes, symbolName, namedType, theOnlyDocumentationCommentTrivia.SyntaxTree)
 
                    ElseIf namedType.TypeKind = TypeKind.Enum OrElse namedType.TypeKind = TypeKind.Module Then
                        ReportIllegalWellKnownTagIfAny(WellKnownTag.TypeParam, wellKnownElementNodes, symbolName)
                        ReportIllegalWellKnownTagIfAny(WellKnownTag.TypeParamRef, wellKnownElementNodes, symbolName)
 
                    Else
                        ReportWarningsForTypeParamTags(wellKnownElementNodes, symbolName, namedType.TypeParameters)
                        ' <typeparamref>
                        ReportWarningsForTypeParamRefTags(wellKnownElementNodes, symbolName, namedType, theOnlyDocumentationCommentTrivia.SyntaxTree)
                    End If
                End If
 
                FreeWellKnownElementNodes(wellKnownElementNodes)
 
                WriteDocumentationCommentForSymbol(docCommentXml)
            End Sub
 
        End Class
 
    End Class
End Namespace