Hi Paul,
> I went through
> the comments and tweaked them in a way that I hope makes them even clearer.
In doing so, unfortunately, in several places you removed the first sentence,
which answered the question "What is its use-case?".
Generally, it's a good guideline to structure the technical documentation of
a feature or function in three parts:
1. Why, when?
2. What?
3. How?
In detail:
1. Answer the question "Why and under which conditions should I use XY?"
2. Answer the question "What does XY do?"
3. Answer the question "How do I use XY? What specific syntax do I have to
use? What are the arguments that I have to pass?"
Many developers tend to write a documentation with 3. "How", or 3. "How"
and 2. "What" intermixed. This is not so good.
Part 1 is important so that people who look for something don't need to read
the entire description before noticing that this is not what they are looking
for. A single sentence should usually be sufficient for that.
Part 2 is for the user to understand the feature / function abstractly, so
that they can think about whether it really fits their use-case.
Part 3 then is for when they have decided that they want to use it, and need
a detailed hands-on description what they have to provide.
Let me try to reinstante the answer to 1. "Why, when", by grouping the macros
according to their use-case.
Hope this still fits your taste.
2020-05-10 Bruno Haible <br...@clisp.org>
attribute: Clarify list of attributes.
* lib/attribute.h: Reorder the list of attributes, and group them by
purpose.
