CxXmlDoc
Description
- 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 := '>=' | '>' | '<=' | '<' ;
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:
-
name: from CxCodeUnit -
type: from CxCodeUnit -
contract: from CxContract
To obtain a CxXmlDoc from source code, use the FromSource method.
Public / Constructors
FromSource
Parses the given Code-X documentation comment.
- ValidatingException
-
If the syntax of source in is invalid.