Here is the document, pasted into the mail instead of being attached:
– Proposal –
User Manual for Clang.
– Intent –
Create and maintain help and maual pages for clang.
– Motivation –
- There is no decent manual that includes everything that clang has to offer.
- Knowladge is spread among few places.
- There are options that are not documented.
- Clang’s users are using GNU’s manuals !$;~(.
– Requirments –
- Accessible documentation for clang.
- Up-to-Date documentation now and in the future.
- Ease of use for developers.
– Background –
When dealing with a compiler, most of the documentation needed by users
is how to use its various options. Developers of the compiler need other
information - this paper does not address them.
A manual is considered a good one if it is being used over and over again,
if one can find everything she needs inside it and, if it gives the right
answer in a short time.
– Technique –
Extend current implementation.
Current implementation has few advantages that we should adhere:
It is simple, uses TableGen.
It is commonly used in LLVM.
– Design –
Coupling between a compilation option and its help text (hereinafter “o-help”,
Adding/fixing/updating a compilation option must include activity on its o-help.
This way documentation keep being relevant.
Decoupling between the o-help and its view. The same o-help may be presented
in various ways. It is one thing to write the documentation and another thing
to present it to the user. We shouldn’t couple between the two. The o-help on its
own shoudln’t have any representation intent. See ‘o-help properties’ below.
Create some sort of enforcememt on developers for actually supply the o-help for
their option. Nice-to-have / optional / not mandatory activities are tend to be
neglected… ending with not up to date documentation.
– O-help properties –
Here is a list of suggested o-help properties to keep along with each compilation option.
- group : as implemented today. the group this option belong to.
- short description : as implemented today. a short description of the option.
- long description : detailed explnation of the option.
- common use : text that describes common use of the option.
- example : the output with and the output without this option.
- commonality (0-2) : how common this option is: 0-most, 1-somtimes, 2-rarely/developers only
- known issues : bugs, limits, etc.
– O-help example –
option : -c
group : compile only
short description : Only run preprocess, compile, and assemble steps
long description :
Compile or assemble the source files, but do not link.
The linking stage simply is not done.
The ultimate output is in the form of an object file for each source file.
By default, the object file name for a source file is made by replacing
the suffix .c, .i, .s, etc., with .o.
Unrecognized input files, not requiring compilation or assembly, are ignored.
common use :
- compiling a single file for the sake of syntactic problems.
not as part of a big-building-process.
- creating objects that are later linked, as a step in a big-building-process
with: clang++ -c foo.cpp
output: foo.o - the object file generated from foo.cpp
without: clang++ foo.cpp
output: a.out - an executable file generated from foo.cpp
commonality (0-2) : 0
known issues : this is a fundamental option, no kwnon issues.
– Uses of o-help –
Since we decouple the o-help from its use,
the usage may vary and evolve with time.
Few usages that are currently in mind:
generating manual pages. o-help properties:
short description, long description, common use, example and known issues
generating --help 's result. o-help properties:
group, short description, commonality(=0)
generating --help's result. o-help properties:
group, short description, commonality(=0-details)
generating html pages. o-help properties:
group, short description, long description,
common use, exampe, commonality (0-2), known issues
imagination is the limit once we have the data.
– Transition –
To transit from current state to fully-up-to-date-documentation state we’ll just
insert some defaults and fill them with time with real, good documentation.
It might look strange a bit at first glance, but what would you prefer as a user:
no documentation at all or ‘will be written soon’?
– Implementation –
Implementation issues will be discussed in a smaller group and will start once the concept is closed.