[MPlayer-dev-eng] code documentation guideline draft

[Diego Biurrun]

I was going to review the content thoroughly, but .. it's perfect ;-)

So I just had my usual spelling/wording nitpicks ..

Attila Kinali writes:
> 
> To tackle this problem every part of MPlayer should follow this guidelines

these guidelines

> which contain the specialy tagged comment lines from the code including

speciaLLy

> cross refenrences. To generate it type `make doxygen` in the source root

references

> - every function, no matter whether it is globaly or just localy used 

globally, locally

>   * where validity checking is done (optional, mandantory for variables which

mandatory

>   * all local definitions which use is not imediatly clear by their name

s/which/whose/

> All comments should be in correct and clear english. Any other language is

English

> The used language should be also a rather simple as the code will
> be read mostly by non-native speakers. For function and variable documentation, a style usable by doxygen should be used. See section 3 "Documenting the code"

I'd rephrase this sentence (and break the overly long line):

The language used should be kept simple as the code will be read
mostly by non-native speakers.

It's somewhat ironic 

> of the doxygen manual for a introduction. A very short overview follows:

s/a/an/

> /// this is line is used by doxygen

This is a line used by doxygen.

> /** this one too */

this one, too

> /** these
> here 
> of
> course
> too */

these here of course, too

> // this line isnt included in doxygen documentation

This line isnt included in doxygen documentation.

> /* neither is this */

Neither is this.

> \brief <one line text>
>    gives a brief description of a function.
> \param <parameter> <text>
>    describes a specific <parameter> 

Here and below I would use proper punctuation and capitalization, the
descriptions are complete sentences.

I'd also remove some trailing whitespace, but that is just my nitpicky
self.

Diego