| Re: [AD] Documentation proposition |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
> Eric, things like this on the stable branch too?
If you want, but don't spend too much time backporting them. Big changes are
supposed to be written against the dev branch, so enhancing ahack._tx is
more important on that branch.
Minor nits:
+One of the nicest thing of Allegro is the excellent manual which you can
+ read
...things (of | in ?) Allegro...
+ in their correct section.
'in the appropriate section' is better I think.
+ This is to have a correct plain text documentation
This rule is needed in order to produce...
+ what are they used for, and never forget to say the accepted range of
+ values for a parameter if any.
what they are for and their range of values (if any).
+ the usage of the function in a real life environment
...in real life.
+ for newbie users
for newbies.
+ if you are writting
Superfluous 't'.
+Whatever coding style applies to Allegro code is also applied to documented
+examples (ie: 8 character tab stops). Of course, all said about documenting
+functions applies to macros and variables too.
Whatever coding style applies to Allegro's code also applies to the
documented examples.
What do you want to say in the last sentence? That the documentation rules
for functions also apply to macros and pointers-to-functions? Then I think
this must be mentioned earlier, at the end of the paragraph on functions.
And 'Similarly for macros and pointers-to-functions' is sufficient.
--
Eric Botcazou