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]
 */

Revision: r1.2 - 01 Aug 2003 - 13:38 - RobVermaas
Stratego > ReleasePlan > ReleasePlan > LibraryDocumentation
Copyright © 1999-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback