NaturalDocs::Languages::CSharp

NaturalDocs::Languages::Advanced

A subclass to handle the language variations of C#.

Summary

NaturalDocs::Languages::CSharp	A subclass to handle the language variations of C#.
Language Support
Package Variables
classKeywords	An existence hash of all the acceptable class keywords.
classModifiers	An existence hash of all the acceptable class modifiers.
functionModifiers	An existence hash of all the acceptable function modifiers.
variableModifiers	An existence hash of all the acceptable variable modifiers.
enumTypes	An existence hash of all the possible enum types.
impossibleTypeWords	An existence hash of all the reserved words that cannot be in a type.
Interface Functions
PackageSeparator	Returns the package separator symbol.
EnumValues	Returns the EnumValuesType that describes how the language handles enums.
ParseFile	Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
Statement Parsing Functions	All functions here assume that the current position is at the beginning of a statement.
TryToGetNamespace	Determines whether the position is at a namespace declaration statement, and if so, adjusts the scope, skips it, and returns true.
TryToGetClass	Determines whether the position is at a class declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetUsing	Determines whether the position is at a using statement, and if so, adds it to the current scope, skips it, and returns true.
TryToGetFunction	Determines if the position is on a function declaration, and if so, generates a topic for it, skips it, and returns true.
TryToGetOverloadedOperator	Determines if the position is on an operator overload declaration, and if so, generates a topic for it, skips it, and returns true.
TryToGetVariable	Determines if the position is on a variable declaration statement, and if so, generates a topic for each variable, skips the statement, and returns true.
TryToGetEnum	Determines if the position is on an enum declaration statement, and if so, generates a topic for it.
TryToGetType	Determines if the position is on a type identifier, and if so, skips it and returns it as a string.
Low Level Parsing Functions
GenericSkip	Advances the position one place through general code.
GenericSkipUntilAfter	Advances the position via GenericSkip() until a specific token is reached and passed.
SkipRestOfStatement	Advances the position via GenericSkip() until after the end of the current statement, which is defined as a semicolon or a brace group.
TryToSkipString	If the current position is on a string delimiter, skip past the string and return true.
TryToSkipAttributes	If the current position is on an attribute section, skip it and return true.
TryToSkipWhitespace	If the current position is on a whitespace token, a line break token, a comment, or a preprocessing directive, it skips them and returns true.
TryToSkipComment	If the current position is on a comment, skip past it and return true.
TryToSkipLineComment	If the current position is on a line comment symbol, skip past it and return true.
TryToSkipMultilineComment	If the current position is on an opening comment symbol, skip past it and return true.
TryToSkipPreprocessingDirective	If the current position is on a preprocessing directive, skip past it and return true.

Language Support

Supported

Classes
Namespaces (no topic generated)
Functions
Constructors and Destructors
Properties
Indexers
Operators
Delegates
Variables
Constants
Events
Enums

Not supported yet

Autodocumenting enum members
Using alias

Package Variables

classKeywords

my %classKeywords

An existence hash of all the acceptable class keywords. The keys are in all lowercase.

classModifiers

my %classModifiers

An existence hash of all the acceptable class modifiers. The keys are in all lowercase.

functionModifiers

my %functionModifiers

An existence hash of all the acceptable function modifiers. Also applies to properties. Also encompasses those for operators and indexers, but have more than are valid for them. The keys are in all lowercase.

variableModifiers

my %variableModifiers

An existence hash of all the acceptable variable modifiers. The keys are in all lowercase.

enumTypes

my %enumTypes

An existence hash of all the possible enum types. The keys are in all lowercase.

impossibleTypeWords

my %impossibleTypeWords

An existence hash of all the reserved words that cannot be in a type. This includes ‘enum’ and all modifiers. The keys are in all lowercase.

Interface Functions

PackageSeparator

sub PackageSeparator

Returns the package separator symbol.

EnumValues

sub EnumValues

Returns the EnumValuesType that describes how the language handles enums.

ParseFile

sub ParseFile #( sourceFile,
topicsList )

Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().

Parameters

sourceFile	The FileName to parse.
topicList	A reference to the list of NaturalDocs::Parser::ParsedTopics being built by the file.

Returns

The array ( autoTopics, scopeRecord ).

autoTopics	An arrayref of automatically generated topics from the file, or undef if none.
scopeRecord	An arrayref of NaturalDocs::Languages::Advanced::ScopeChanges, or undef if none.

Statement Parsing Functions

All functions here assume that the current position is at the beginning of a statement.

Note for developers: I am well aware that the code in these functions do not check if we’re past the end of the tokens as often as it should. We’re making use of the fact that Perl will always return undef in these cases to keep the code simpler.

TryToGetNamespace

sub TryToGetNamespace #( indexRef,
lineNumberRef )

Determines whether the position is at a namespace declaration statement, and if so, adjusts the scope, skips it, and returns true.

Why no topic?

The main reason we don’t create a Natural Docs topic for a namespace is because in order to declare class A.B.C in C#, you must do this:

namespace A.B
   {
   class C
       { ... }
   }

That would result in a namespace topic whose only purpose is really to qualify C. It would take the default page title, and thus the default menu title. So if you have files for A.B.X, A.B.Y, and A.B.Z, they all will appear as A.B on the menu.

If something actually appears in the namespace besides a class, it will be handled by NaturalDocs::Parser->AddPackageDelineators(). That function will add a package topic to correct the scope.

If the user actually documented it, it will still appear because of the manual topic.

TryToGetClass

sub TryToGetClass #( indexRef,
lineNumberRef )

Determines whether the position is at a class declaration statement, and if so, generates a topic for it, skips it, and returns true.

Supported Syntaxes

Classes
Structs
Interfaces

TryToGetUsing

sub TryToGetUsing #( indexRef,
lineNumberRef )

Determines whether the position is at a using statement, and if so, adds it to the current scope, skips it, and returns true.

Supported

Using

Unsupported

Using with alias

TryToGetFunction

sub TryToGetFunction #( indexRef,
lineNumberRef )

Determines if the position is on a function declaration, and if so, generates a topic for it, skips it, and returns true.

Supported Syntaxes

Functions
Constructors
Destructors
Properties
Indexers
Delegates
Events

TryToGetOverloadedOperator

sub TryToGetOverloadedOperator #( indexRef,
lineNumberRef )

Determines if the position is on an operator overload declaration, and if so, generates a topic for it, skips it, and returns true.

TryToGetVariable

sub TryToGetVariable #( indexRef,
lineNumberRef )

Determines if the position is on a variable declaration statement, and if so, generates a topic for each variable, skips the statement, and returns true.

Supported Syntaxes

Variables
Constants

TryToGetEnum

sub TryToGetEnum #( indexRef,
lineNumberRef )

Determines if the position is on an enum declaration statement, and if so, generates a topic for it.

Supported Syntaxes

Enums
Enums with declared types

Unsupported

Documenting the members automatically

TryToGetType

sub TryToGetType #( indexRef,
lineNumberRef )

Determines if the position is on a type identifier, and if so, skips it and returns it as a string. This function does not allow modifiers. You must take care of those beforehand.

Low Level Parsing Functions

GenericSkip

sub GenericSkip #( indexRef,
lineNumberRef )

Advances the position one place through general code.

If the position is on a string, it will skip it completely.
If the position is on an opening symbol, it will skip until the past the closing symbol.
If the position is on whitespace (including comments and preprocessing directives), it will skip it completely.
Otherwise it skips one token.

Parameters

indexRef	A reference to the current index.
lineNumberRef	A reference to the current line number.

GenericSkipUntilAfter

sub GenericSkipUntilAfter #( indexRef,
lineNumberRef,
token )

Advances the position via GenericSkip() until a specific token is reached and passed.

SkipRestOfStatement

sub SkipRestOfStatement #( indexRef,
lineNumberRef )

Advances the position via GenericSkip() until after the end of the current statement, which is defined as a semicolon or a brace group. Of course, either of those appearing inside parenthesis, a nested brace group, etc. don’t count.

TryToSkipString

sub TryToSkipString #( indexRef,
lineNumberRef )

If the current position is on a string delimiter, skip past the string and return true.

Parameters

indexRef	A reference to the index of the position to start at.
lineNumberRef	A reference to the line number of the position.

Returns

Whether the position was at a string.

Syntax Support

Supports quotes, apostrophes, and at-quotes.

TryToSkipAttributes

sub TryToSkipAttributes #( indexRef,
lineNumberRef )

If the current position is on an attribute section, skip it and return true. Skips multiple attribute sections if they appear consecutively.

TryToSkipWhitespace

sub TryToSkipWhitespace #( indexRef,
lineNumberRef )

If the current position is on a whitespace token, a line break token, a comment, or a preprocessing directive, it skips them and returns true. If there are a number of these in a row, it skips them all.

TryToSkipComment

sub TryToSkipComment #( indexRef,
lineNumberRef )

If the current position is on a comment, skip past it and return true.

TryToSkipLineComment

sub TryToSkipLineComment #( indexRef,
lineNumberRef )

If the current position is on a line comment symbol, skip past it and return true.

TryToSkipMultilineComment

sub TryToSkipMultilineComment #( indexRef,
lineNumberRef )

If the current position is on an opening comment symbol, skip past it and return true.

TryToSkipPreprocessingDirective

sub TryToSkipPreprocessingDirective #( indexRef,
lineNumberRef )

If the current position is on a preprocessing directive, skip past it and return true.