Generates the xml files of help from the head comments of a .sci file or a directory.
help_xml = slr_comments_to_xml(src) help_xml = slr_comments_to_xml(src, help_dir)
source file or directory to be processed.
directory in which the help file(s) will be placed
This routines generates .xml help files based on the head comments of .sci files. Note that the head comments can either be made with single line comments or with block comments.
In order for this routine to format the .xml file properly, the head comments should comply with some simple formatting rules.
In particular, the head comments should be divided in different sections which content is then specifically formatted. The predefined sections are: 'Syntax', 'Parameters', 'Description', 'Examples', 'See also', 'Used functions', 'Authors' and 'Bibliography'. To be recognised, these headlines should be alone on a line.
The content of each section must also comply with some rules to be formatted adequately:
a one-line description of the function should be located between the declaration of the function and the first section.
Syntax: shows examples of call to the routine. There should be one example of call per line.
Parameters: contains the list of input and output parameters with a short description.
The name of the parameter is separated from its description by a ":" and the type of the parameter can be put in parenthesis just after its name.
Note that the description of the parameter can extends on several lines.
Description: this section enables to describe more in-depth the behaviour of the routine.
To ease the formatting of the text, some markdown-like features are supported (see below).
Examples: contains full use cases of the routine. The formatting is similar to the description section and the code snippet become executable.
See also: enables to provide links to similar functions. Each name must be on a new line or be separated by a comma.
Bibliography: contains references to the litterature. Each entry must be separated from the other by a newline or a comma.
Authors: contains a list of the authors. Each author must appear on a different line.
A basic markdown support is implemented for the sections description, examples, and any user defined section.
It supports:
bold expressions are delimited with ** or __
italic expression are delimited with * or _
literal expressions
are delimited with `
unordered lists are obtained using * at the start of the line. Indentation is then exploited to determine nested lists.
Paragraph in lists are obtained with a single newline. Note that they must end with a point to be parsed correctly.
code blocks are delimited with ~~~
inline latex equations are delimited with $
Here is an example of the results this function can produce
target = './'; // where the xml file will be created xml_str = slr_comments_to_xml([], target); // with an empty source, it will apply to itself my_title = 'slr_comments_to_xml_demo'; xmltojar(target, my_title) // generate a jar file from the xml ok = add_help_chapter(my_title,target); // adding the help chapter help(); | ![]() | ![]() |