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* keep* ;
!exception := '<exception' 'cref' '=' '"' name '"' '>' body
'</exception>' ;
!keep := '<keep' 'cref' '=' '"' ref '"' '/>' ;
!param := '<param' 'name' '=' '"' id '"' '>' contract? body \ '['
'</param>' ;
!remarks := '<remarks>' body '</remarks>' ;
!returns := '<returns>' contract? body '</returns>' ;
!see-also := '<seealso' 'cref' '=' '"' ref '"' '/>' ;
!summary := '<summary>' body '</summary>' ;
!type-param := '<typeparam' 'name' '=' '"' id '"' '>' body '</typeparam>' ;
!value := '<value>' contract? body '</value>' ;
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 := name ref-arguments? ('.' ref-member)? ref-signature? ;
ref-signature := '(' (type .. ',')? ')' ;
see := ws-ast? '<see' 'cref' '=' '"' ref '"' '/>' ;
ref-member := id ref-arguments? ;
!param-ref := ws-ast? '<paramref' 'name' '=' '"' id '"' '/>' ;
ref-arguments := '{' (id .. ',') '}' ;
!type-param-ref := ws-ast? '<typeparamref' 'name' '=' '"' id '"' '/>' ;
c := ws-ast? '<c>' text+ '</c>' ;
code := '<code>' ws* lb line+ '</code>' ;
br := '<br/>' ws* lb ;
line := ws* ~(lb | '</code>')* lb ;
text := (]\t\n\r &<[ | 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.
Public / Attributes
Keep
Returns the custom keep sections.
When the Code-X workflow performs source code minification and obfuscation, usually some code elements must not be removed or their names must not be changed, because they are referenced by native code (see CxStatementCode).
The // [*] line-comment suffix may be used to keep a local variable in a statement block (see CxStatementVariable):
int thisMayBeRenamed; int thisWillBeKept; // [*]
The _keep name suffix may also be used to keep local variables:
for (int current_keep = 0; ...) { ... }
foreach (var current_keep in ...) { ... }
At member or type scope, the custom XmlDoc element keep may be used to keep the referenced code element:
/// <summary>
/// A member with a keep rule.
/// </summary>
/// <keep cref="SomeType.SomeMethod(int)"/>
void SomeMember() { ... }
By using the [Keep] attribute, the annotated type, member or parameter will be kept:
[Keep]
class SomeType { ... }
...
[Keep]
void SomeMember() { ... }
...
void Member([Keep] someParameter) { ... }
In order to maximize the effectiveness of source code minification and obfuscation, the rules for keeping code elements should be applied according to the following best-practice:
-
Use
// [*]for keeping local variables, because this is the most compact syntax. If not applicable, use the_keepname suffix. -
Use the custom XmlDoc tag
<keep cref="…"/>, because this will trigger the keep rule only if the enclosing type or member is actually included in the final output. -
Use the
[Keep]attribute for method parameters if a parameter shall be kept for the whole method. This will trigger the keep rule only if the enclosing member is actually included in the final output. -
Use the
[Keep]attribute on a member, if it shall be kept if the enclosing type is actually included in the final output. This is generally true for members with private visibility. The enclosing type may still be discarded, though. -
Use the
[Keep]attribute on a type, if it shall be kept. Individual type members may still be discarded, though.