The isisscripts
help text file is extracted from the source file. Every text enclosed
in
%!%+
% ...
% ...
%!%-
is interpreted as help text and requires a few macros to be present (see below). In general it doesn't matter where the help section appears in the source code, but it is good practice (and therefore highly recommended) that the help is in the function body. Every function, except under certain circumstances, that is publicly available and meant to be called by a user is expected to have a help text that describes at least how the function is called its synopsis. The following paragraphs describe the available macros to format the help text and some guidelines.
Providing help
The minimal help text that is required looks something like
%!%+
%\function{my_fancy_function}
%\synopsis{Simple sentence that describes my_fancy_function}
%\usage{Return_Type my_fancy_function (Input_Type [, Optional_Input_Type]);}
%!%-
\function formats the function name and is used for assignment, missing it will not display the help
text when called with help my-fancy-function
.
Formatting Macros
\altusage
If the described function has more than one calling signature, it is possible to give alternatives with \altusage{Alternative_Return_Type my_fancy_function(Input_Type, Input_Type, ...);}. It is important that \altusage is allways completely contained in the \usage call, otherwise formatting is messed up.
Example:
%\usage{Return_Type my_fancy_function (Input_Type);
%\altusage{Alt_Return_Type my_fancy_function (Alt_Input_Type);}}
\qualifiers
The \qualifiers macro collects all calls of \qualifier where ach qualifier is represented as name - description pair \qualifier{my_nice_qualifier}{: Fancy qualifier for fancy function}. If a qualifier is not just a flag but has a value, it is a good idea to give the default value in the description as \qualifier{qualifier_with_value}{[=Default_Value]: Description text}
Example:
%\qualifiers{
%\qualifier{fancy_flag}{: enables flag1 feature}
%\qualifier{fancy_qual}{[=NULL]: provides additional info}
%}
\description
The description macro will only provide a heading for the description section and does not operate on any input. A description is not allways necessary if the function is allready sufficiently described by the synopsis and the usage text.
Example:
%\description
% Here is some more information on how the function can be used
% to do cool stuff.
The indentation is not required but gives a more readable help for the command line.
\seealso
The \seealso macro is used to give hints on functions that could provide additional information, do similar tasks or are subroutines of the current function. \seealso should only be given as the last part of the help and list just some (<5) other functions.
Example:
%\seealso{others_fancy_function, fancy_subroutine, very_similar}
\code
The \code macro can be used in the qualifier or function description to mark a text as code.
Example:
% This description describes a stupid line of code
% \code{variable foo = 0+1*0; % this is nonsense}
\example/\examples
The \example or \examples macros take no arguments but can be used to insert 'Example' or 'Examples' as headings in the description. Complicated functions are far more easier to use, if they provide an minimal working example.
Example:
%\description
% Here is some text to explain what the function is used
% for. The following example shows what needs to be done.
%\example
% % This is the setup
% variable a_dummy_variable = 5;
% variable struct_for_function = struct { a = 1, b = NULL };
% variable return_value = my_fancy_function (a_dummy_variable, struct_for_function; nice_qualifier);
\wikilink
\wikilink allows to give one or more references to a page of the wiki. It is expected that the path is given from the root of the wiki without leading /. The link is displayed as either the text after the last slash or if a '#' is present (for a link to a heading) the text following is used (with '-' replaced by space). Multiple links can be separated by colons.
Guidlines
This section describes a few points how the help should be given and what information should be provided. In general is it expected that a help text gives the following information in this order:
%\function{}
%\synopsis{}
%\usage{}
%\description
%\examples
%\seealso{}
-
The usage should contain all possible variants of the function call with the corresponding variable type. Optional arguments should be given in square brackets.
-
If the function takes or returns a structure it is expected that the function description lists the structure members and there meaning.