[Glsdk-devel] API reference conventions

[H. H. <hen...@gm...>]

Okay, I am writing the GLM API reference manual pages and I think we should
decide on some doc conventions.

1) Should we use verbs in imperative form or in present tense form? For
example, which is better:
* (imperative) Convert radians into degrees.
* (present tense) Converts radians into degrees.

2) What is the general layout of a reference pages? Some ideas:

------
DESCRIPTION
  Converts radians into degrees.

  Parameters
    radians -- radians to convert

  Return value
    Returns *radians* as degrees.


or perhaps:
------
DESCRIPTION
  Converts radians into degrees.

PARAMETERS
  radians -- radians to convert

RETURN VALUE
  Returns *radians* as degrees.


Other sections; SEE ALSO, COPYRIGHT etc.


3) Anything else we should decide on?


At some point we should establish documentation editors who would have
access to our SVN 'docs/' subdirectory, and who go through the docs and
correct any misspellings and typos and check the conformance against our
conventions. These editors should be native English speakers, which I am
not.

-- 
Henri 'henux' Häkkinen