NaturalDocs::Languages::CSharp

NaturalDocs::Languages::CSharp

A subclass to handle the language variations of C#.

Summary
NaturalDocs::Languages::CSharpA subclass to handle the language variations of C#.
Language Support
Package Variables
classKeywordsAn existence hash of all the acceptable class keywords.
classModifiersAn existence hash of all the acceptable class modifiers.
functionModifiersAn existence hash of all the acceptable function modifiers.
variableModifiersAn existence hash of all the acceptable variable modifiers.
enumTypesAn existence hash of all the possible enum types.
impossibleTypeWordsAn existence hash of all the reserved words that cannot be in a type.
Interface Functions
PackageSeparatorReturns the package separator symbol.
EnumValuesReturns the EnumValuesType that describes how the language handles enums.
ParseFileParses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
Statement Parsing FunctionsAll functions here assume that the current position is at the beginning of a statement.
TryToGetNamespaceDetermines whether the position is at a namespace declaration statement, and if so, adjusts the scope, skips it, and returns true.
TryToGetClassDetermines whether the position is at a class declaration statement, and if so, generates a topic for it, skips it, and returns true.
TryToGetUsingDetermines whether the position is at a using statement, and if so, adds it to the current scope, skips it, and returns true.
TryToGetFunctionDetermines if the position is on a function declaration, and if so, generates a topic for it, skips it, and returns true.
TryToGetOverloadedOperatorDetermines if the position is on an operator overload declaration, and if so, generates a topic for it, skips it, and returns true.
TryToGetVariableDetermines if the position is on a variable declaration statement, and if so, generates a topic for each variable, skips the statement, and returns true.
TryToGetEnumDetermines if the position is on an enum declaration statement, and if so, generates a topic for it.
TryToGetTypeDetermines if the position is on a type identifier, and if so, skips it and returns it as a string.
Low Level Parsing Functions
GenericSkipAdvances the position one place through general code.
GenericSkipUntilAfterAdvances the position via GenericSkip() until a specific token is reached and passed.
SkipRestOfStatementAdvances the position via GenericSkip() until after the end of the current statement, which is defined as a semicolon or a brace group.
TryToSkipStringIf the current position is on a string delimiter, skip past the string and return true.
TryToSkipAttributesIf the current position is on an attribute section, skip it and return true.
TryToSkipTemplateSpecIf the current position is on a template spec (the part in angle brackets) skip it and return true.
TryToSkipWhereClausesIf the current position is on a “where” clause, skips it and returns true.
TryToSkipWhitespaceIf the current position is on a whitespace token, a line break token, a comment, or a preprocessing directive, it skips them and returns true.
TryToSkipCommentIf the current position is on a comment, skip past it and return true.
TryToSkipLineCommentIf the current position is on a line comment symbol, skip past it and return true.
TryToSkipMultilineCommentIf the current position is on an opening comment symbol, skip past it and return true.
TryToSkipPreprocessingDirectiveIf 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

sourceFileThe FileName to parse.
topicListA reference to the list of NaturalDocs::Parser::ParsedTopics being built by the file.

Returns

The array ( autoTopics, scopeRecord ).

autoTopicsAn arrayref of automatically generated topics from the file, or undef if none.
scopeRecordAn 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

indexRefA reference to the current index.
lineNumberRefA 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

indexRefA reference to the index of the position to start at.
lineNumberRefA 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.

TryToSkipTemplateSpec

sub TryToSkipTemplateSpec #(indexRef,
lineNumberRef)

If the current position is on a template spec (the part in angle brackets) skip it and return true.  Can handle nested templates.

TryToSkipWhereClauses

sub TryToSkipWhereClauses #(indexRef,
lineNumberRef)

If the current position is on a “where” clause, skips it and returns true.  Can handle multiple wheres in a row.

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.

The base class for all languages that have full support in Natural Docs.
my %classKeywords
An existence hash of all the acceptable class keywords.
my %classModifiers
An existence hash of all the acceptable class modifiers.
my %functionModifiers
An existence hash of all the acceptable function modifiers.
my %variableModifiers
An existence hash of all the acceptable variable modifiers.
my %enumTypes
An existence hash of all the possible enum types.
my %impossibleTypeWords
An existence hash of all the reserved words that cannot be in a type.
sub PackageSeparator
Returns the package separator symbol.
sub EnumValues
Returns the EnumValuesType that describes how the language handles enums.
How enum values are handled in the language.
sub ParseFile #(sourceFile,
topicsList)
Parses the passed source file, sending comments acceptable for documentation to NaturalDocs::Parser->OnComment().
sub OnComment #(string[] commentLines,
int lineNumber,
bool isJavaDoc)
The function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation.
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.
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.
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.
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.
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.
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.
sub TryToGetEnum #(indexRef,
lineNumberRef)
Determines if the position is on an enum declaration statement, and if so, generates a topic for it.
sub TryToGetType #(indexRef,
lineNumberRef)
Determines if the position is on a type identifier, and if so, skips it and returns it as a string.
sub GenericSkip #(indexRef,
lineNumberRef)
Advances the position one place through general code.
sub GenericSkipUntilAfter #(indexRef,
lineNumberRef,
token)
Advances the position via GenericSkip() until a specific token is reached and passed.
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.
sub TryToSkipString #(indexRef,
lineNumberRef)
If the current position is on a string delimiter, skip past the string and return true.
sub TryToSkipAttributes #(indexRef,
lineNumberRef)
If the current position is on an attribute section, skip it and return true.
sub TryToSkipTemplateSpec #(indexRef,
lineNumberRef)
If the current position is on a template spec (the part in angle brackets) skip it and return true.
sub TryToSkipWhereClauses #(indexRef,
lineNumberRef)
If the current position is on a “where” clause, skips it and returns true.
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.
sub TryToSkipComment #(indexRef,
lineNumberRef)
If the current position is on a comment, skip past it and return true.
sub TryToSkipLineComment #(indexRef,
lineNumberRef)
If the current position is on a line comment symbol, skip past it and return true.
sub TryToSkipMultilineComment #(indexRef,
lineNumberRef)
If the current position is on an opening comment symbol, skip past it and return true.
sub TryToSkipPreprocessingDirective #(indexRef,
lineNumberRef)
If the current position is on a preprocessing directive, skip past it and return true.
A string representing the absolute, platform-dependent path to a file.
A class for parsed topics of source files.
A class used to store a scope change.
sub AddPackageDelineators
Adds section and class topics to make sure the package is correctly represented in the documentation.
Close