Library Documentation

The documentation of Stratego Standard Library^? must be improved. You can help with this in two ways:

• If you have to you think longer than 10 seconds about what a strategy in the SSL actually does, please write your understanding down and send it to the stratego-dev mailing list. One of the maintainers will add your contribution to the sources. Preferable use an xDoc documentation comment, but plain text descriptions are welcome as well.

• If you contribute a new strategy to the library you must document it if you want your contribution to be useful. Of course you should use an xDoc documentation comment for this.

A documentation comment should consist of

• One line description of what the strategy does.
• Optional some paragraphs where you explain the strategy in more details. It is useful to include some example applications and the expected result of these applications.
• Use @param to describe the purpose of term and strategy arguments
• Use @type to specify the type of the strategy and its term and strategy arguments
• Use @since to specify from which release the strategy has been be available

e.g.

/**
 * Generates lists of numbers.
 * 
 * The given end point is never part of the generated list; <range> 10 generates a list of 10 values, 
 * exactly the legal indices for items of a sequence of length 10. It is possible to let the range 
 * start at another number.
 *
 * <range> 10 => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 * <range> (5, 10)     => [5, 6, 7, 8, 9]
 *
 * The documentation of the range strategy is partly copied from the Python tutorial.
 *
 * @since 0.9.3
 * @type Int * Int -> [Int]
 */

For useful tips and conventions for writing descriptions in doc comments see xDoc style guide.

---

Discussion

This is an excellent idea. I have a few comments.

Including example applications is fine, but if they are just comments they tend not to be maintained properly and may contain syntactic and semantic errors. Would it be an idea to make the examples more formal, i.e., with an official syntax, and derive unit tests from them?

Examples are fine for small strategies, but more complicated for more complex strategies. An early version of the rename-vars module contained a complete example application in comment. The problem of examples in comments increases considerable for such large examples. It might be useful to recognize examples that are provided in a separate module. For instance, one can imagine having a subdirectory full of examples for some module, as well as unit tests.

-- EelcoVisser - 03 Aug 2003