cfe-dev Digest, Vol 59, Issue 42

  1. While emphasizing manual work for documantation, how do you explain the fact that there is no user manul for clang?

  2. I really don’t want to go into implementation details. We could extend current implementation or switch to a super-high-end-class-documentation tool -

The idea of seperating the data from its representation is the important issue.

This is the o-help key/index that must be embedded in code and by using it we enter a world of data regarding the option.

I think that “ should still contain a small, one-line description of each option for the purpose of --help etc” is the root of the problem. We couple the use to the data.

There are many developers that don’t use command line and still want to have short description of a compilation option (for example by a tool-tip when hovering over a checkbox with the mouse).

The discussion should be therefore:
What fields/data/column/properties/name-it-as-you-like should be part of the database of each option?
What are the fields that when having them we can generate any representation we love?
What is the underlaying data that can keep a good documentation with time?

For example, if we want the data to be structured later by some sort of hierarchy, as suggested below, we must then add hierarchy-value. I thought that the ‘group’ property is enough, creating one-level-hierarchy. But if someone think that more is needed, please explain and give an example.

And remember, I really don’t want this discussion to be on the ‘How’ side at the moment. Let’s close the ‘What’ first.