The following message is a courtesy copy of an article that has been posted to epita.cours.compile as well. 2004-03-16 Akim Demaille <akim@epita.fr> * assignments.texi (Documentation Style): Document flyspell-prog-mode, Doxygen limitations (capitalization of sentences), and namespace documentation location. --- /home/akim/www/compil/assignments.txt 2004-03-16 09:13:35.000000000 +0100 +++ assignments.txt 2004-03-16 10:16:23.000000000 +0100 @@ -1565,6 +1565,26 @@ 2.3.7 Documentation Style ------------------------- + -- Rule: Write correct English + Nowadays most editors provide interactive spell checking including for + programs (strings and comments). For instance, see `flyspell-mode' in + Emacs, and in particular the `flyspell-prog-mode'. To trigger it + automatically, install the following in your `~/.emacs.el': + + (add-hook 'c-mode-hook 'flyspell-prog-mode 1) + (add-hook 'c++-mode-hook 'flyspell-prog-mode 1) + (add-hook 'cperl-mode-hook 'flyspell-prog-mode 1) + (add-hook 'sh-mode-hook 'flyspell-prog-mode 1) + (add-hook 'makefile-mode-hook 'flyspell-prog-mode 1) + + and so forth. + + End comments with a period. + + 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. + -- 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, @@ -1581,7 +1601,7 @@ /// Swap the two references and return the first. ref& swap (ref& other); - The same rules apply to writing ChangeLogs. + The same rules apply to ChangeLogs. -- Rule: Use `rebox.el' to markup paragraphs Often one wants to leave a clear markup to separate different matters. @@ -1599,13 +1619,28 @@ | Comments end with a period. | `-----------------------------*/ - -- Rule: Prefer Doxygen Documentation to plain comments - We use Doxygen (*note Doxygen::) to maintain the developer - documentation of the Tiger Compiler. - -- Rule: Write Documentation in Doxygen - Documentation is a genuine part of programming, just as testing. The - quality of this documentation can change the grade. + Documentation is a genuine part of programming, just as testing. We + use Doxygen (*note Doxygen::) to maintain the developer documentation + of the Tiger Compiler. The quality of this documentation can change + the grade. + + Beware that Doxygen puts the first letter of the documentation in upper + case. As a result, + + /// \file ast/arrayexp.hh + /// \brief ast::ArrayExp declaration. + + will not work properly, since `ast::ArrayExp' will be transformed into + `Ast::ArrayExp' by Doxygen, which will not be recognized as an entity + name. As a workaround, write the slightly longer: + + /// \file ast/arrayexp.hh + /// \brief Declaration of ast::ArrayExp. + + -- Rule: Document namespaces in `lib*.hh' files + -- Rule: Document classes in their `*.hh' file + There must be a single location, that's our standard. -- Rule: Use `\directive' Prefer backslash (`\') to the commercial at (`@') to specify