This class handles the creation of LaTeX documentation from code files. It will detect documentation keywords, but the resulting files will not be compiled automatically. This is in the responsibility of the calling function. More...

#include <docgen.hpp>

Inheritance diagram for DocumentationGenerator:

Collaboration diagram for DocumentationGenerator:

Public Member Functions
	DocumentationGenerator (NumeReSyntax *_syntax, const std::string &sRootPath)
	DocumentationGenerator constructor. More...

std::string	createDocumentation (const std::string &sFileName) const
	This member function creates a LaTeX documentation from a single file and stores it. It's not compilable due to missing main and style files. More...

std::string	createFullDocumentation (const std::string &sFileName) const
	This member function creates a LaTeX documentation from the passed file and all dependent files. All necessary files for compilation are created. More...

Public Member Functions inherited from FileSystem
	FileSystem ()
	Default constructor. More...

FileSystem &	assign (const FileSystem &_fSys)
	Assignment member function to copy the settings from another FileSystem instance. More...

std::string	ValidFileName (std::string _sFileName, const std::string sExtension=".dat", bool checkExtension=true, bool doCleanPath=true) const
	This member function evaluates, whether the passed filename is a valid filename. One may supply a preferred filename extension. More...

std::string	ValidFolderName (std::string _sFileName, bool doCleanPath=true, bool appendTrailingSeparator=true) const
	This member function evaluates, whether the passed foldername is a valid foldername. More...

std::string	ValidizeAndPrepareName (const std::string &_sFileName, const std::string &sExtension=".dat") const
	This member function validizes the passed file name and creates the needed folders on-the-fly. More...

int	setPath (std::string _sPath, bool bMkDir, std::string _sExePath)
	This member function may be used to set the preferred file path of the current FileSystem instance. More...

void	createRevisionsFolder ()
	This member function creates the hidden revisions folders for the version control system. More...

std::string	getPath () const
	Returns the default path of this FileSystem instance. More...

std::vector< std::string >	getFileParts (const std::string &sFilePath) const
	This member function separates all path parts into single strings: the drive letter, the path, the name and the extension. This function may also handle folder paths and network paths. More...

FileInfo	getFileInfo (const std::string &sFilePath) const
	Return the file information about the passed file path. More...

void	setTokens (std::string _sTokens)
	This member function may be used to update the path placeholders of the current FileSystem instance. More...

bool	isFile (const std::string &_sPath) const
	This function determines, whether a path name indicates a file or a folder. More...

void	initializeFromKernel ()
	Member function to remote-initialize the class from the kernel. Cannot be used during kernel start-up. More...

void	setProgramPath (std::string _sExePath)

std::string	getProgramPath () const

void	declareFileType (const std::string &sFileType)

Private Member Functions
void	followBranch (const std::string &sFile, std::set< std::string > &fileSet, std::vector< std::string > &vFiles) const
	This member function finds all dependent procedure files. If the current file is not a procedure, the recursion terminates. More...

std::string	convertToLaTeX (const std::string &sFileName) const
	Writes the content of the current code file to a LaTeX file. More...

std::string	getStrippedRange (const StyledTextFile &file, int pos1, int pos2, bool encode=true) const
	Gets the contents of the selected range. More...

std::string	parseDocumentation (const StyledTextFile &file, const std::string &sMainProc, int pos1, int pos2) const
	Converts the documentation into LaTeX code. More...

std::string	createParametersTable (const std::vector< std::string > &vParams) const
	This member function creates a table out of the declared parameters in the documentation comments. More...

std::string	createReturnsTable (const std::vector< std::string > &vParams) const
	This member function creates a table out of the declared return values in the documentation comments. More...

size_t	findListItem (const std::string &sTextRange, size_t &nLength) const
	This helper function finds the next list item in the passed documentation string. More...

std::string	createMainProcedure (std::string sFileName) const
	This method converts the passed filename into a main procedure for the current file. More...

std::string	createLaTeXFileName (std::string sFileName) const
	This method will create a target filename for the TeX files and create the needed folder structure on-the-fly. More...

std::string	prepareFileNameForLaTeX (std::string sFileName) const
	This member function removes the path parts of the default paths and masks underscores, which will confuse the LaTeX parser. More...

std::string	constructKeyWords (std::string sKeyWordList) const
	This member function replaces the passed whitespace-separated keyword list with a comma-separated list. More...

void	createStyleFile () const
	This member function writes the LaTeX header file used to highlight the code snippets, which are part of the created code documentation. The contents of the header file are read from the corresponding template file in the "lang" folder. More...

std::string	createMainFile (const std::string &sFileName, const std::vector< std::string > &vIncludesList, const std::vector< std::string > &vFiles) const
	This member function creates a main LaTeX file including the perviously created LaTeX documentation files. More...

Private Attributes
NumeReSyntax *	m_syntax

Additional Inherited Members
Protected Member Functions inherited from FileSystem
int	createFolders (const std::string &_sPath) const
	This member function creates all missing directories in the passed path. More...

Protected Attributes inherited from FileSystem
std::string	sPath

std::string	sExecutablePath

std::string	sTokens [7][2]

std::string	sValidExtensions

Detailed Description

This class handles the creation of LaTeX documentation from code files. It will detect documentation keywords, but the resulting files will not be compiled automatically. This is in the responsibility of the calling function.

Definition at line 40 of file docgen.hpp.

Constructor & Destructor Documentation

◆ DocumentationGenerator()

DocumentationGenerator::DocumentationGenerator	(	NumeReSyntax *	_syntax,
		const std::string &	sRootPath
	)

DocumentationGenerator constructor.

Parameters

_syntax	NumeReSyntax*
sRootPath	const std::string&

Definition at line 956 of file docgen.cpp.

References NumeReKernel::getInstance(), m_syntax, and FileSystem::setPath().

Here is the call graph for this function:

Member Function Documentation

◆ constructKeyWords()

std::string DocumentationGenerator::constructKeyWords ( std::string sKeyWordList ) const

private

This member function replaces the passed whitespace-separated keyword list with a comma-separated list.

Parameters

sKeyWordList std::string

Returns: std::string

Definition at line 805 of file docgen.cpp.

Referenced by createStyleFile().

◆ convertToLaTeX()

std::string DocumentationGenerator::convertToLaTeX ( const std::string & sFileName ) const

private

Writes the content of the current code file to a LaTeX file.

Parameters

sFileName const std::string&

Returns: std::string

The contents of the current code file are converted into a LaTeX file, where the code sections are printed as listings and the documentation strings are used as normal text.

Definition at line 95 of file docgen.cpp.

References StyledTextFile::COMMENT_BLOCK, StyledTextFile::COMMENT_DOC_BLOCK, StyledTextFile::COMMENT_DOC_LINE, StyledTextFile::COMMENT_LINE, createLaTeXFileName(), createMainProcedure(), StyledTextFile::getLastPosition(), StyledTextFile::getLineEndPosition(), getStrippedRange(), StyledTextFile::getStyleAt(), StyledTextFile::getTextRange(), StyledTextFile::LineFromPosition(), parseDocumentation(), and StyledTextFile::PositionFromLine().

Referenced by createDocumentation(), and createFullDocumentation().

Here is the call graph for this function:

◆ createDocumentation()

std::string DocumentationGenerator::createDocumentation ( const std::string & sFileName ) const

This member function creates a LaTeX documentation from a single file and stores it. It's not compilable due to missing main and style files.

Parameters

sFileName const std::string&

Returns: std::string

Definition at line 973 of file docgen.cpp.

References convertToLaTeX(), and replacePathSeparator().

Referenced by NumeReWindow::createLaTeXFile().

Here is the call graph for this function:

◆ createFullDocumentation()

std::string DocumentationGenerator::createFullDocumentation ( const std::string & sFileName ) const

This member function creates a LaTeX documentation from the passed file and all dependent files. All necessary files for compilation are created.

Parameters

sFileName const std::string&

Returns: std::string

Definition at line 994 of file docgen.cpp.

References convertToLaTeX(), createMainFile(), createStyleFile(), followBranch(), and replacePathSeparator().

Referenced by NumeReWindow::runLaTeX().

Here is the call graph for this function:

◆ createLaTeXFileName()

std::string DocumentationGenerator::createLaTeXFileName ( std::string sFileName ) const

private

This method will create a target filename for the TeX files and create the needed folder structure on-the-fly.

Parameters

sFileName std::string

Returns: std::string

Remarks: The returned filename does not contain any file extension.

Definition at line 718 of file docgen.cpp.

References FileSystem::createFolders(), EXEPATH, NumeReKernel::getInstance(), FileSystem::getPath(), NumeReKernel::getPathSettings(), PROCPATH, and SCRIPTPATH.

Referenced by convertToLaTeX(), and createMainFile().

Here is the call graph for this function:

◆ createMainFile()

std::string DocumentationGenerator::createMainFile	(	const std::string &	sFileName,
		const std::vector< std::string > &	vIncludesList,
		const std::vector< std::string > &	vFiles
	)		const

private

This member function creates a main LaTeX file including the perviously created LaTeX documentation files.

Parameters

sFileName	const std::string&
vIncludesList	const std::vector<std::string>&
vFiles	const std::vector<std::string>&

Returns: std::string

Definition at line 900 of file docgen.cpp.

References createLaTeXFileName(), FileSystem::getPath(), and prepareFileNameForLaTeX().

Referenced by createFullDocumentation().

Here is the call graph for this function:

◆ createMainProcedure()

std::string DocumentationGenerator::createMainProcedure ( std::string sFileName ) const

private

This method converts the passed filename into a main procedure for the current file.

Parameters

sFileName std::string

Returns: std::string

Definition at line 678 of file docgen.cpp.

References NumeReKernel::getInstance(), NumeReKernel::getPathSettings(), PROCPATH, and replaceAll().

Referenced by convertToLaTeX().

Here is the call graph for this function:

◆ createParametersTable()

std::string DocumentationGenerator::createParametersTable ( const std::vector< std::string > & vParams ) const

private

This member function creates a table out of the declared parameters in the documentation comments.

Parameters

vParams const std::vector<std::string>&

Returns: std::string

Definition at line 565 of file docgen.cpp.

References replaceAll().

Referenced by parseDocumentation().

Here is the call graph for this function:

◆ createReturnsTable()

std::string DocumentationGenerator::createReturnsTable ( const std::vector< std::string > & vReturns ) const

private

This member function creates a table out of the declared return values in the documentation comments.

Parameters

vReturns const std::vector<std::string>&

Returns: std::string

Definition at line 616 of file docgen.cpp.

References replaceAll().

Referenced by parseDocumentation().

Here is the call graph for this function:

◆ createStyleFile()

void DocumentationGenerator::createStyleFile ( ) const

private

This member function writes the LaTeX header file used to highlight the code snippets, which are part of the created code documentation. The contents of the header file are read from the corresponding template file in the "lang" folder.

Returns: void

Definition at line 831 of file docgen.cpp.

References constructKeyWords(), NumeReSyntax::getCommands(), NumeReSyntax::getConstants(), NumeReSyntax::getFunctions(), NumeReKernel::getInstance(), NumeReSyntax::getMethods(), NumeReSyntax::getNPRCCommands(), NumeReSyntax::getOptions(), FileSystem::getPath(), NumeReSyntax::getSpecial(), and m_syntax.

Referenced by createFullDocumentation().

Here is the call graph for this function:

◆ findListItem()

size_t DocumentationGenerator::findListItem	(	const std::string &	sTextRange,
		size_t &	nLength
	)		const

private

This helper function finds the next list item in the passed documentation string.

Parameters

sTextRange	const std::string&
nLength	size_t&

Returns: size_t

Definition at line 651 of file docgen.cpp.

Referenced by parseDocumentation().

◆ followBranch()

void DocumentationGenerator::followBranch	(	const std::string &	sFile,
		std::set< std::string > &	fileSet,
		std::vector< std::string > &	vFiles
	)		const

private

This member function finds all dependent procedure files. If the current file is not a procedure, the recursion terminates.

Parameters

sFile	const std::string&
fileSet	std::set<std::string>&
vFiles	std::vector<std::string>&

Returns: void

Definition at line 39 of file docgen.cpp.

References followBranch(), ProcedureElement::getDependencies(), Dependencies::getDependencyMap(), getEventProcedures(), NumeReKernel::getInstance(), ProcedureLibrary::getProcedureContents(), NumeReKernel::getProcedureLibrary(), and replacePathSeparator().

Referenced by createFullDocumentation(), and followBranch().

Here is the call graph for this function:

◆ getStrippedRange()

std::string DocumentationGenerator::getStrippedRange	(	const StyledTextFile &	file,
		int	pos1,
		int	pos2,
		bool	encode = `true`
	)		const

private

Gets the contents of the selected range.

Parameters

file	StyledTextFile representation of the loaded file
pos1	int first character to extract
pos2	int last character to extract
encode	bool encode umlauts

Returns: std::string

The content between both positions is returned without leading and trailing whitespaces, tabulators and line ending characters. Carriage returns in the middle of the selection are omitted and only line endings are kept. If the encoding option is activated, then umlauts are converted into their two-letter representation.

Definition at line 242 of file docgen.cpp.

References StyledTextFile::getTextRange().

Referenced by convertToLaTeX(), and parseDocumentation().

Here is the call graph for this function:

◆ parseDocumentation()

std::string DocumentationGenerator::parseDocumentation	(	const StyledTextFile &	file,
		const std::string &	sMainProc,
		int	pos1,
		int	pos2
	)		const

private

Converts the documentation into LaTeX code.

Parameters

file	StyledTextFile representation of the loaded file
sMainProc	const std::string&
pos1	int
pos2	int

Returns: string

The documentation extracted from the code comments is converted to LaTeX text. This includes:

unordered lists
german umlauts
inline code sequences

Definition at line 322 of file docgen.cpp.

References createParametersTable(), createReturnsTable(), findListItem(), ProcedureElement::getDependencies(), Dependencies::getDependencyMap(), StyledTextFile::getFileName(), NumeReKernel::getInstance(), ProcedureLibrary::getProcedureContents(), NumeReKernel::getProcedureLibrary(), getStrippedRange(), and replaceAll().

Referenced by convertToLaTeX().

Here is the call graph for this function:

◆ prepareFileNameForLaTeX()

std::string DocumentationGenerator::prepareFileNameForLaTeX ( std::string sFileName ) const

private

This member function removes the path parts of the default paths and masks underscores, which will confuse the LaTeX parser.

Parameters

sFileName std::string

Returns: std::string

Definition at line 764 of file docgen.cpp.

References NumeReKernel::getInstance(), NumeReKernel::getPathSettings(), LOADPATH, and PATH_LAST.

Referenced by createMainFile().

Here is the call graph for this function:

Member Data Documentation

◆ m_syntax

NumeReSyntax* DocumentationGenerator::m_syntax

private

Definition at line 43 of file docgen.hpp.

Referenced by createStyleFile(), and DocumentationGenerator().

The documentation for this class was generated from the following files:

D:/CPP/numere-source/trunk/kernel/core/documentation/docgen.hpp
D:/CPP/numere-source/trunk/kernel/core/documentation/docgen.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DocumentationGenerator()

Member Function Documentation

◆ constructKeyWords()

◆ convertToLaTeX()

◆ createDocumentation()

◆ createFullDocumentation()

◆ createLaTeXFileName()

◆ createMainFile()

◆ createMainProcedure()

◆ createParametersTable()

◆ createReturnsTable()

◆ createStyleFile()

◆ findListItem()

◆ followBranch()

◆ getStrippedRange()

◆ parseDocumentation()

◆ prepareFileNameForLaTeX()

Member Data Documentation

◆ m_syntax