On 13 Feb 2001, Marcin 'Qrczak' Kowalczyk wrote:
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).
Most of what you suggest seems acceptable. Few minor points though: ---------------------------------------------------- ---- Subsection blah ---------------------------------------------------- The first and the third line are just visual ASCII hints but they have no real meaning. A formatter will use its own means of presentation, so they could be safely stripped off. My extractor currently arbitrarily ignores any top level sequence of 8 dashes or more.
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.)
OK, I see your point about the SEE business. But the second part of my previous suggestion can be rephrased using your caps idea: To clarify, FUNCTION doesDirectoryExist returns True ... or To clarify, FUNCTION 'doesDirectoryExist' returns True ... The first version carries the semantics only, while the second one has an additional formatting information -- which can be nevertheless considered redundant. BTW, I see Malcolm's point about single quote; but (') just looks lighter in plain ascii and it maybe worthwhile supporting it by a careful parsing. Alternatively, a simple rule: "Double the single quote, or escape it (\'), if you want it printed" would do. Smalltalk uses the doubling rule (their strings are in single quotes, and double quotes signify comments), and its users are happy enough with it. Underscores are fine, but they are also ambiguous since some of the function names use them as well. And I bet that some of us dislike Hungarian notation and use underscores aboundantly. But the same doubling or escape rules could be applied here as well. Jan