La section de Tiger pour la documentation a du sens pour Vaucanson et Olena. http://www.lrde.epita.fr/~akim/compil/assignments.html#Documentation-Style 2004-03-18 Akim Demaille <akim(a)epita.fr> * assignments.texi (T3 Goals): More. (T5 Goals): Traits are now part of... (T3 Goals): these. (Documentation Style): More about useless words/comments. --- /home/akim/www/compil/assignments.txt 2004-03-17 10:39:27.000000000 +0100 +++ assignments.txt 2004-03-18 11:44:38.000000000 +0100 @@ -5,7 +5,7 @@ The Tiger Compiler Project ************************** - This document, last edited on March 17, 2004, details the various tasks + This document, last edited on March 18, 2004, details the various tasks the "Compilation" students must complete. It is available under various forms: - Assignments in a single HTML file(1). @@ -1617,10 +1617,51 @@ End comments with a period. + -- Rule: Be concise For documentation as for any other kind of writing, the shorter, the better: hunt useless words. *Note The Elements of Style::, for an excellent set of writing guidelines. + Here are a few samples of things to avoid: + Documenting the definition instead of the object of the definition + Don't write: + + /// Declaration of the Foo class. + class Foo + { + ... + }; + + Of course you're documentation the definition of the entities! + "Declaration of the" is totally useless, just use `/// Foo + class'. But read bellow. + + Don't qualify obvious entity kinds. + Don't write: + + /// Foo class. + class Foo + { + public: + /// Construct a Foo object. + Foo (Bar &bar) + ... + }; + + It is so obvious that you're documentation the class and the + constructor that you should not write it down. Instead of + documenting the _kind_ of an entity (class, function, namespace, + destructor...), document its _goal_. + + /// Wrapper around Bar objects. + class Foo + { + public: + /// Bind to \a bar. + Foo (Bar &bar) + ... + }; + -- Rule: Use the Imperative Use the imperative when documenting, as if you were giving order to the function or entity you are describing. When describing a function,