Editing Adding new programs to Madagascar (section)

==How to document your program==
There are three levels of documentation. From the most simple to the most complex, they are: in-code documentation, the Wiki, and reproducible papers. 
===In-code documentation===
Of course, do comment your code -- focusing on "why" (the code itself describes the "how"). Keep comments sparse so that as much code as possible can be kept in mind at the same time by the human reader. Use the other levels for more information.
 
If you follow a certain syntax for some of your comments, then the scripts in the Madagascar framework will be able to automatically produce a self-doc page for your program. This page will be displayed in the terminal (using basic text-mode formatting) when the program is invoked without any arguments, and a HTML version will be automatically generated in $RSFDOC (default: $RSFROOT/doc). The self-doc page has the following sections: <tt>Name</tt>, <tt>Description</tt>, <tt>Synopsis</tt>, <tt>Comments</tt>, <tt>Parameters</tt>, <tt>Used in</tt>, <tt>Source</tt> and <tt>Version</tt>. 
====Self-doc for C programs====
To automatically populate the <tt>Description</tt> and <tt>Comments</tt> sections, use the following syntax. Start the file with:
<syntaxhighlight lang="c">
/* Short description line
Comments here blablabla lorem ipsum dolores sit amet...

You can use several paragraphs for comments, no problem.*/

/* Copyright notice */
</syntaxhighlight>
Notice that: (1) the description line is the first line in the file; (2) Comments are closed and then open again on a new line for Copyright (so that Copyright does not show up in the documentation).

To make input parameters and their default values (if they exist) automatically appear in the <tt>Synopsis</tt> and <tt>Parameters</tt> sections, make sure to read the parameters in the code like in the following example:
<syntaxhighlight lang="c">
if (!sf_getbool("su",&su)) su=false;
/* y if input is SU, n if input is SEGY */
</syntaxhighlight>
Notice that there are no complex logical operations inside the <tt>if</tt>, that there is no space between the equal sign and the right and left hand, and that a short comment follows immediately. If by necessity the parameter is read in a complex fashion, use angular brackets inside the short line following the read block, i.e.:
<pre>
... sf_getfloat ... complex stuff ...
/*< parameter_name parameter meaning >*/
</pre>

====Self-doc for Python programs====
To automatically populate the <tt>Description</tt> page, and <tt>Comments</tt> sections, use the following syntax. Start the file with:
<syntaxhighlight lang="python">
#! /usr/bin/env python
'''My one-line description of this program
If I have comments, put them in the lines below.

I can use several paragraphs for that'''

# Copyright notice...
</syntaxhighlight>
Then, make sure to
<syntaxhighlight lang="python">
import rsfprog
</syntaxhighlight>
To make input parameters and their default values (if they exist) automatically appear in the <tt>Synopsis</tt> and <tt>Parameters</tt> sections, make sure to follow each argument read with a comment, and call <tt>selfdoc</tt> if no argument was given. Here is an example from <tt>user/ivlad/Mpclip.py</tt>:
<syntaxhighlight lang="python">
    par = rsf.Par(argv)

    inp = par.string('inp') # input file
    out = par.string('out') # output file
    if None in (inp, out):
        rsfprog.selfdoc()   # self-doc
        return error

    verb = par.bool('verb', False) # if y, print system commands, outputs
</syntaxhighlight>

====Self-doc for Fortran 90 programs====
To automatically populate the <tt>Description</tt> section (<tt>Comments</tt> is not available), use the following syntax. Start the file with:
<pre>
! One-line short description, leave a blank line after it

! Copyright notice...
</pre>

To make input parameters and their default values (if they exist) automatically appear in the <tt>Synopsis</tt> and <tt>Parameters</tt> sections, make sure to read the parameters in the code like in the following example:
<pre>
call from_par( "n1", nt, 512 ) ! Param description on same line or first line after
</pre>

===Wiki documentation===
The self-doc is good as a reminder of what the parameters mean and what their default values are, but more is usually needed for someone who never used the tool. This is what the [[Guide to madagascar programs|Guide to programs]] is for. Whenever you change or create a program, make sure to add a section for it in there too, if possible with an implementation section. Documenting programs that already exist is also a great idea.

You may have noticed that each program section on that page starts with a table that has the same content as the self-doc. That is created automatically the following way. Say you want to create this table for <tt>sfattr</tt>. At a command line, type:
<pre>
sfdoc -m $HOME attr
</pre>
This will create the file <tt>$HOME/sfattr.wiki</tt>. Its content can be copied and pasted into the Madagascar wiki, as they already are in the MediaWiki format. Another directory can be used instead of $HOME.

If your program/script reads an environment variable, make sure you check [[Advanced Installation#Environment variables|the list of environment variables used by Madagascar]] and add your new variable or your peculiar usage of an existing variable.

After creating the appropriate section in the [[Guide to madagascar programs|Guide to programs]], add your program name without the <tt>sf</tt> prefix to the <tt>docprogs</tt> list at the beginning of <tt>RSFSRC/framework/rsf/doc.py</tt> . This will ensure that a link to the wiki section is created in the auto-generated HTML program page in <tt>$RSFDOC</tt>.

Add your program to the [[Task-centric program list]] so that it can be found by those users who do not already know they need it.

===Reproducible documents===
<tt>Madagascar</tt> programs are tested and illustrated by means of [[Reproducible_Documents|reproducible documents]]. See the [[Reproducible computational experiments using SCons|Guide to SCons interface for reproducible computations]] for a brief explanation of what a reproducible paper is and how to produce one.