Scilab Documentation Convention
Why should I use code documentation ?
Scilab is an open source project. As a result, many people are working on it and there are always some people entering the project and some leaving. Specially if you don't have any experienced Scilab developper to help you, it might be very difficult to understand the poorly documented code. The time spent documenting is, without any doubt, much lower than the one needed by the next person who will read the code.
Like in any professional project, we recommend to document the code. However, even if a software is used to generate online documentation, some rules are needed to achieve a consistent result, easier to understand. So we present a list of basic rules each developpers is asked to follow.
The aim of automatic documentation is to get an easier understanding on how to use somebody else code without actually reading it. The description of functions, structures and other data should be clear enough. Nobody should need to enter the code to use them. The major point of documentation is to write for other people, not for yourself. When writting always consider that someone else will read your comments.
Here is a set of rules to keep in mind:
- When modifying existing code, it is critically important that any associated source code documentation be updated and kept coherent with the code. Without this, the documentation becomes unreliable and then unusable.
- All classes, structures, defines and global variables should contain a comment describing its meaning and usage in the code.
- Always explain first what things are doing, what they stand for. It is often not useful to know how the things are done (does everybody want to know how the Scilab parser is working?).
- Only use high level descriptions.
- Don't hesitate to use the grouping capabilities of Doxygen.
- Only header files need to be documented. Since all the declaration are in the header file, it is meaningless to add more description in the .c files.
- A short description of the file must be added to explain what we will find in. It will also prevent programmers to add code which is not linked with the purpose of the file.
- The authors have to be written there.
- At least one sentence is needed for each function to explain its purpose.
One should also document the parameters. It is recommended to add the [in], [out] or [in,out] qualifiers for arrays and pointers.
- Any special cases must also be documented. Remember users don't want to read your code.
- For mathematic functions, don't hesitate to introduce latex expressions.
- The comments should be written just before the function and begin with /**.
- A description of the purpose of the structure should be written above.
Each element must be documented. In this case the description should be put on the same line using /**<
Describing others data
Comment all define, typedef, enum, union,... Everything might not be as obvious as you can think. For enum, it may be interesting to comment each constant.