[cfe-dev] User Manual (mail-embedded)
joerg at britannica.bec.de
Thu May 10 01:54:02 PDT 2012
On Thu, May 10, 2012 at 08:19:15AM +0300, Ran Regev wrote:
> -- Technique --
> Extend current implementation.
> Current implementation has few advantages that we should adhere:
> It is simple, uses TableGen.
> It is commonly used in LLVM.
I'll comment on this part, since it is the heart. Let's take a look at GCC's
info and man page for a moment to see what is wrong with and what works.
The man page tends to be abysmal. It is created automatically from the
info page with a fancy and somewhat broken toolchain. It has lots of
structural (and lack thereof) and syntactical issues. It certainly
proves that a man page listening thousands of options has very limited
use. The info page is somewhat better, since it is hierachical and
navigable. How do you want to get a well structured document by
semi-automatically rearranging entries from *Options.td? I consider this
the same problem as with Doxygen style documentation. It is nice if you
want to document the available methods of a class, but starts to become
limiting when you want to give a more high level discription of a
- *de*couple the manual from *Options.td and choose the right tools (as
in format) for the job. Plain HTML, docbook, sphinx -- many options
exits for this
- require (comment) markers in the manual to identify which options are
- provide automated tools to verify consistency between the set of
documented and implemented options
*Options.td should still contain a small, one-line description of each
option for the purpose of --help etc, but I expect most options to end
up with a more detailed text than that.
To summarize: being able to freely shuffle texts around is critical for
documentation. Source code is not the best tool for documentation.
Coherency issues can be avoided by using appropiate markers.
More information about the cfe-dev