adding the code documentation guide lines

now everyone has to follow them


git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@13291 b3059339-0415-0410-9bf9-f77b7e298cf2

1 files changed, 124 insertions, 0 deletions

diff --git a/DOCS/tech/code-documentation.txt b/DOCS/tech/code-documentation.txt
new file mode 100644
index 0000000000..6da2b53379
--- /dev/null
+++ b/DOCS/tech/code-documentation.txt
@@ -0,0 +1,124 @@
+Code documentation guidelines
+=============================
+
+About this guide
+----------------
+
+Due to the ever increasing complexity and size of MPlayer it became quite hard
+to maintain the code and add new features. Part of this problem is the lack
+of proper documentation what the code in question does and how it is doing it.
+To tackle this problem every part of MPlayer should follow these guidelines
+on what and how code should be documented.
+
+
+Doxygen
+-------
+
+MPlayer uses doxygen for its code documentation. It generates HTML files
+which contain the specially tagged comment lines from the code including
+cross references. To generate it type `make doxygen` in the source root
+directory. It will generate the files in DOCS/tech/doxygen. To clear them
+again, you can use `make doxygen_clean`.
+For further information about doxygen and its sources please have a look
+at their website: http://doxygen.sf.net
+
+
+What should be documented?
+--------------------------
+
+- every function, no matter whether it is globally or just locally used
+  * what the function does
+  * all parameters and return values of the function and their valid ranges
+  * all side effects (to passed parameters, globals etc)
+  * all assumptions made within the function
+
+- global, file local and important variables
+  * what it is used for
+  * its valid range
+  * where it is set (optional)
+  * where validity checking is done (optional, mandatory for variables which
+    are set by something external, eg user parameters, file information etc)
+
+- #define, typedefs, structs
+  * all global definitions
+  * all local definitions whos use is not imediatly clear by their name
+    (as a rule of thumb, it's better to document too much then not enough)
+  * all dependencies
+
+- non-trivial parts of the code
+  * tricky parts
+  * important parts
+  * special side effects
+  * assumptions of the code
+  * string operations and why they are safe
+
+- workarounds
+ * why they are needed
+ * how they work
+ * what side effects they have
+
+If you are unsure whether a comment is needed or not, add one.
+
+
+How should it be documented?
+----------------------------
+
+All comments should be in correct and clear English. Any other language is
+not allowed. The language used should be kept 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"
+of the doxygen manual for an introduction. A very short overview follows:
+
+Doxygen includes only special comments in the documentation, those are:
+
+/// This is a line used by doxygen.
+
+/** this one, too */
+
+/** these
+here
+of
+course,
+too */
+
+//! this form can be also used
+
+// This line isn't included in doxygen documentation.
+
+/* Neither is this. */
+
+There are a couple of special tags for doxygen:
+
+\brief <one line text>
+   Gives a brief description of a function.
+\param <parameter> <text>
+   Describes a specific <parameter>.
+\return <text>
+   Describes the return value.
+\a <word>
+   Mark next word as a reference to a parameter.
+\e <word>
+   Use italic font for the next word.
+\b <word>
+   Use bold font for the next word.
+\c <word>
+   Use typewriter font for the next word.
+\sa <references>
+   Adds a section with crossreferences.
+\bug <text>
+   Describe a known bug.
+\todo <text>
+   Add a todo list.
+\attention <text>
+   Add a section for something that needs attention.
+\warning <text>
+   Add a section for a warning.
+\anchor <refname>
+   Set an invisible anchor which can be used to create a link with /ref.
+\ref <refname> [<text>]
+   Add a link to <refname>.
+
+For a complete list of tags please read section 20 "Special commands" of the
+doxygen manual.
+
+