A package that coordinates source file parsing between the NaturalDocs::Languages::Base-derived objects and its own sub-packages such as NaturalDocs::Parser::Native. Also handles sending symbols to NaturalDocs::SymbolTable and other generic topic processing.
| NaturalDocs:: | A package that coordinates source file parsing between the NaturalDocs::Languages::Base-derived objects and its own sub-packages such as NaturalDocs::Parser::Native. |
| Variables | |
| sourceFile | The source FileName currently being parsed. |
| language | The language object for the file, derived from NaturalDocs::Languages::Base. |
| parsedFile | An array of NaturalDocs::Parser::ParsedTopic objects. |
| parsingForInformation | Whether ParseForInformation() was called. |
| Functions | |
| ParseForInformation | Parses the input file for information. |
| ParseForBuild | Parses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref. |
| Interface Functions | |
| OnComment | The function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation. |
| OnClass | A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a class declaration. |
| OnClassParent | A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a declaration of inheritance. |
| Support Functions | |
| Parse | Opens the source file and parses process. |
| CleanComment | Removes any extraneous formatting and whitespace from the comment. |
| Processing Functions | |
| RepairPackages | Recalculates the packages for all comment topics using the auto-topics and the scope record. |
| MergeAutoTopics | Merges the automatically generated topics into the file. |
| RemoveRemainingHeaderlessTopics | After MergeAutoTopics() is done, this function removes any remaining headerless topics from the file. |
| MakeAutoGroups | Creates group topics for files that do not have them. |
| MakeAutoGroupsFor | Creates group topics for sections of files that do not have them. |
| AddToClassHierarchy | Adds any class topics to the class hierarchy, since they may not have been called with OnClass() if they didn’t match up to an auto-topic. |
| AddPackageDelineators | Adds section and class topics to make sure the package is correctly represented in the documentation. |
| BreakLists | Breaks list topics into individual topics. |
| GetSummaryFromBody | Returns the summary text from the topic body. |
| GetSummaryFromDescriptionList | Returns the summary text from a description list entry. |
my $sourceFile
The source FileName currently being parsed.
my $language
The language object for the file, derived from NaturalDocs::Languages::Base.
my @parsedFile
An array of NaturalDocs::Parser::ParsedTopic objects.
my $parsingForInformation
Whether ParseForInformation() was called. If false, then ParseForBuild() was called.
sub ParseForInformation #( file )
Parses the input file for information. Will update the information about the file in NaturalDocs::SymbolTable and NaturalDocs::Project.
| file | The FileName to parse. |
sub ParseForBuild #( file )
Parses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref.
Note that all new and changed files should be parsed for symbols via ParseForInformation() before calling this function on any file. The reason is that NaturalDocs::SymbolTable needs to know about all the symbol definitions and references to resolve them properly.
| file | The FileName to parse for building. |
An arrayref of the source file as NaturalDocs::Parser::ParsedTopic objects.
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.
| commentLines | An arrayref of the comment’s lines. The language’s comment symbols should be converted to spaces, and there should be no line break characters at the end of each line. The original memory will be changed. |
| lineNumber | The line number of the first of the comment lines. |
| isJavaDoc | Whether the comment is in JavaDoc format. |
The number of topics created by this comment, or zero if none.
sub OnClass #( class )
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a class declaration.
| class | The SymbolString of the class encountered. |
sub OnClassParent #( class, parent, scope, using, resolvingFlags )
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a declaration of inheritance.
| class | The SymbolString of the class we’re in. |
| parent | The SymbolString of the class it inherits. |
| scope | The package SymbolString that the reference appeared in. |
| using | An arrayref of package SymbolStrings that the reference has access to via “using” statements. |
| resolvingFlags | Any Resolving Flags to be used when resolving the reference. RESOLVE_NOPLURAL is added automatically since that would never apply to source code. |
sub Parse
Opens the source file and parses process. Most of the actual parsing is done in NaturalDocs::Languages::Base->ParseFile() and OnComment(), though.
Do not call externally. Rather, call ParseForInformation() or ParseForBuild().
The default menu title of the file. Will be the FileName if nothing better is found.
sub CleanComment #( commentLines )
Removes any extraneous formatting and whitespace from the comment. Eliminates comment boxes, horizontal lines, trailing whitespace from lines, and expands all tab characters. It keeps leading whitespace, though, since it may be needed for example code, and blank lines, since the original line numbers are needed.
| commentLines | An arrayref of the comment lines to clean. The original memory will be changed. Lines should have the language’s comment symbols replaced by spaces and not have a trailing line break. |
sub RepairPackages #( autoTopics, scopeRecord )
Recalculates the packages for all comment topics using the auto-topics and the scope record. Call this before calling MergeAutoTopics().
| autoTopics | A reference to the list of automatically generated NaturalDocs::Parser::ParsedTopics. |
| scopeRecord | A reference to an array of NaturalDocs::Languages::Advanced::ScopeChanges. |
sub MergeAutoTopics #( language, autoTopics )
Merges the automatically generated topics into the file. If an auto-topic matches an existing topic, it will have it’s prototype and package transferred. If it doesn’t, the auto-topic will be inserted into the list unless NaturalDocs::Settings->DocumentedOnly() is set. If an existing topic doesn’t have a title, it’s assumed to be a headerless comment and will be merged with the next auto-topic or discarded.
| language | The NaturalDocs::Languages::Base-derived class for the file. |
| autoTopics | A reference to the list of automatically generated topics. |
sub RemoveRemainingHeaderlessTopics
After MergeAutoTopics() is done, this function removes any remaining headerless topics from the file. If they don’t merge into anything, they’re not valid topics.
sub MakeAutoGroupsFor #( startIndex, endIndex )
Creates group topics for sections of files that do not have them. A support function for MakeAutoGroups().
| startIndex | The index to start at. |
| endIndex | The index to end at. Not inclusive. |
The number of group topics added.
sub AddToClassHierarchy
Adds any class topics to the class hierarchy, since they may not have been called with OnClass() if they didn’t match up to an auto-topic.
sub GetSummaryFromBody #( body )
Returns the summary text from the topic body.
| body | The complete topic body, in NDMarkup. |
The topic summary, or undef if none.
sub GetSummaryFromDescriptionList #( description )
Returns the summary text from a description list entry.
| description | The description in NDMarkup. Should be the content between the <dd></dd> tags only. |
The description summary, or undef if none.
The source FileName currently being parsed.
my $sourceFile
The language object for the file, derived from NaturalDocs::Languages::Base.
my $language
An array of NaturalDocs::Parser::ParsedTopic objects.
my @parsedFile
Whether ParseForInformation() was called.
my $parsingForInformation
Parses the input file for information.
sub ParseForInformation #( file )
Parses the input file for building, returning it as a NaturalDocs::Parser::ParsedTopic arrayref.
sub ParseForBuild #( file )
The function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a comment suitable for documentation.
sub OnComment #( string[] commentLines, int lineNumber, bool isJavaDoc )
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a class declaration.
sub OnClass #( class )
A function called by NaturalDocs::Languages::Base-derived objects when their parsers encounter a declaration of inheritance.
sub OnClassParent #( class, parent, scope, using, resolvingFlags )
Opens the source file and parses process.
sub Parse
Removes any extraneous formatting and whitespace from the comment.
sub CleanComment #( commentLines )
Recalculates the packages for all comment topics using the auto-topics and the scope record.
sub RepairPackages #( autoTopics, scopeRecord )
Merges the automatically generated topics into the file.
sub MergeAutoTopics #( language, autoTopics )
After MergeAutoTopics() is done, this function removes any remaining headerless topics from the file.
sub RemoveRemainingHeaderlessTopics
Creates group topics for files that do not have them.
sub MakeAutoGroups
Creates group topics for sections of files that do not have them.
sub MakeAutoGroupsFor #( startIndex, endIndex )
Adds any class topics to the class hierarchy, since they may not have been called with OnClass() if they didn’t match up to an auto-topic.
sub AddToClassHierarchy
Adds section and class topics to make sure the package is correctly represented in the documentation.
sub AddPackageDelineators
Breaks list topics into individual topics.
sub BreakLists
Returns the summary text from the topic body.
sub GetSummaryFromBody #( body )
Returns the summary text from a description list entry.
sub GetSummaryFromDescriptionList #( description )
Returns whether undocumented code aspects should be included in the output.
sub DocumentedOnly