Tue, 13 Feb 2001 05:58:49 -0500 (EST), Jan Skibinski
Should the documention standard respect the module authors' wishes and provide at least some sort of support for 'categories'? I think, it should.
I agree. Sections of a module could be separated by "lots of dashes" with a section title together with them (either on the same line or on the next). We can allow a tool to distinguish chapters/sections/subsections by decreasing numbers of dashes. Don't define which number corresponds to which level - just anything above a threshold (e.g. >= 8) marks a part, and different lengths can mark different levels (if the tool supports different levels). Let's say that comments marked by "--" are ignored by the documentation tool, unless it's a pretty printer of the whole source. Comments marked by "---" are basic descriptions of entities: each comment refers to an entity if it's adjacent to it, or is a standalone comment if it doesn't. Comments marked by eight dashes or more are section headers. (Or four?) These rules (after precise definitions of the details) are enough to have a concrete tool which produces a summary of a module (extracting type signatures etc. from the source), formatted in any format (HTML, LaTeX, text). Anything more specific will be compatible with this simple view: we can add keywords for more precise control, but comments with keywords can be emitted as is by a simple tool. Keywords don't require special punctuation. They can be spelled in ALL CAPS so that pure English text is not taken as a keyword by mistake. For example EXPORTED (so that we can distinguish what should go into the interface documentation and what should go only to browsable internals), and custom keywords to be specified with an invocation of a sophisticated doc tool to have project-specific subsetting of the documentation. A remaining thing is hyperlinks to different entities or modules (or fully qualified entities). It's easy to have SEE as a keyword, but we also want to mark an identifier used as a part of a sentence, e.g. To clarify, @doesDirectoryExist@ returns True if a file system object exist, and it's a directory. @doesFileExist@ returns True if the file system object exist, but it's not a directory (i.e., for every other file system object that is not a directory.) (this is a real quotation - I don't suggest to use @ in particular). The same concept can be uniformly applied to quoted chunks of code. In this case a tool can make hyperlinks to names it recognizes if it wishes. Let me stop at this point, and clarify one detail about basic recognition of kinds of comments. For a block of comment lines the form of the first line matters, so it can be equivalently written ---- Overview of the foo process ---- ---- Blah blah blah ---- blah blah blah or ---- Overview of the foo process -- -- Blah blah blah -- blah blah blah -- __("< Marcin Kowalczyk * qrczak@knm.org.pl http://qrczak.ids.net.pl/ \__/ ^^ SYGNATURA ZASTÊPCZA QRCZAK