CxXmlDoc

Description

sealed class Tinman.Core.Cx.XmlDoc.CxXmlDoc

Derived from

CxNode abstract

Represents the documentation comment of a type declaration, a member declaration or an enumeration item.

A Code-X compliant documentation comment is a standard CSharp XmlDoc comment, with additional syntactic and semantic rules and concepts. The syntax of a Code-X documentation comment (not including the leading '/// ') is defined by the following Grammar:

#                := ws | lb ;
root             := xmldoc ;

!xmldoc          := summary remarks? type-param* param* (returns | value)? exception*
                    see-also* ;

!exception       := '<exception' 'cref' '=' '"' (id .. '.') '"' '>' body
                    '</exception>' ;
!param           := '<param' 'name' '=' '"' id '"' '>' pre? body \ '['
                    '</param>' ;
!remarks         := '<remarks>' body '</remarks>' ;
!returns         := '<returns>' body '</returns>' ;
!see-also        := '<seealso' 'cref' '=' '"' ref '"' '/>' ;
!summary         := '<summary>' body '</summary>' ;
!type-param      := '<typeparam' 'name' '=' '"' id '"' '>' body '</typeparam>' ;
!value           := '<value>' body '</value>' ;

!pre             := '[' (pre-simple | pre-compare | pre-interval) ']' ;

pre-compare      := pre-compare-op pre-expr ;
pre-interval     := pre-expr '..' pre-expr ;
pre-simple       := 'not-empty' | 'not-null' | 'pow2+1' | 'pow2' ;

pre-compare-op   := '>=' | '>' | '&lt;=' | '&lt;' ;
pre-expr         := pre-expr-primary !> '-' pre-expr-primary ;

pre-expr-primary := pre-expr-literal | pre-expr-name ;

pre-expr-literal := '-'? dec-digit+ ;
pre-expr-name    := 'global::'? (id .. '.') ;

body             := para+ | body-item+ ;
body-item        := text | see | c | list | code | br | param-ref | type-param-ref ;
!list            := '<list' 'type' '=' list-type '>' list-item+ '</list>' ;
list-item        := '<item>' body '</item>' ;
!para            := '<para>' body-item+ '</para>' ;
!ref             := (id .. '.') (ref-arguments ('.' ref-member)? | ref-signature)? ;
ref-member       := id ref-signature? ;
ref-signature    := '(' (type .. ',')? ')' ;
see              := ws-ast? '<see' 'cref' '=' '"' ref '"' '/>' ;

!param-ref       := ws-ast? '<paramref' 'name' '=' '"' id '"' '/>' ;
ref-arguments    := '{' (id .. ',') '}' ;
!type-param-ref  := ws-ast? '<typeparamref' 'name' '=' '"' id '"' '/>' ;

c                := '<c>' text+ '</c>' ;
code             := '<code>' ws* lb line+ '</code>' ;

br               := '<br/>' ws* lb ;
line             := ws* ~(lb | '</code>')* lb ;
text             := (]<\t\r& \n[ | entity)+ ;
ws-ast           := (ws | lb)+ ;

entity           := '&' ('amp' | 'lt' | 'gt') ';' ;
lb               := '\r' '\n'? | '\n' ;
list-type        := '"bullet"' | '"number"' ;
ws               := '\t' | ' ' ;

The following external rules are used:

To obtain a CxXmlDoc from source code, use the FromSource method.

Public / Constructors

CxXmlDoc


public constructor CxXmlDoc → (7)

summary in : CxXmlDocBody

[not-null]
See Summary.

remarks opt : CxXmlDocBody = null

See Remarks.

typeParameters opt : IBagConst<CxXmlDocTypeParameter> = null

The list of type parameters or null for an empty list. See TypeParameters.

parameters opt : IBagConst<CxXmlDocParameter> = null

The list of parameters or null for an empty list. See Parameters.

value opt : CxXmlDocValue = null

See Value.

exceptions opt : IBagConst<CxXmlDocException> = null

The list of thrown exceptions or null for an empty list. See Exceptions.

seeAlso opt : IBagConst<CxXmlDocSeeAlso> = null

The list of documentation links or null for an empty list. See SeeAlso.

Creates a new instance of CxXmlDoc.

FromSource


public static method FromSource → (1)

source in : string

[not-null]
The documentation comment text.

returns → CxXmlDoc

The parsed Code-X documentation comment.

Parses the given Code-X documentation comment.

ValidatingException

If the syntax of source in is invalid.

Public / Attributes

Exceptions


public attribute Exceptions → (get)

value : IVectorConst<CxXmlDocException>

[not-null]
The <exception> sections.

Returns the <exception> sections.

Parameters


public attribute Parameters → (get)

value : IVector<CxXmlDocParameter>

[not-null]
The <param> sections

Returns the <param> sections.

Remarks


public attribute Remarks → (get)

value : CxXmlDocBody

The <remarks> section.

Returns the <remarks> section.

SeeAlso


public attribute SeeAlso → (get)

value : IVectorConst<CxXmlDocSeeAlso>

[not-null]
The <seealso> sections

Returns the <seealso> sections.

Summary


public attribute Summary → (get)

value : CxXmlDocBody

[not-null]
The <summary> section.

Returns the <summary> section.

TypeParameters


public attribute TypeParameters → (get)

value : IVectorConst<CxXmlDocTypeParameter>

[not-null]
The <typeparam> sections.

Returns the <typeparam> sections.

Value


public attribute Value → (get)

value : CxXmlDocValue

The <returns> resp. <value> section.

Returns the <returns> resp. <value> section.

See also

CxMemberProperty