summaryrefslogtreecommitdiffstats
path: root/DOCS/tech/code-documentation.txt
diff options
context:
space:
mode:
authorattila <attila@b3059339-0415-0410-9bf9-f77b7e298cf2>2004-09-09 01:13:26 +0000
committerattila <attila@b3059339-0415-0410-9bf9-f77b7e298cf2>2004-09-09 01:13:26 +0000
commit3145bff020c1ac789d680452aa38c3f50f3be098 (patch)
tree198448b3ffc414e52fc8f10f13bef2972e1dd52f /DOCS/tech/code-documentation.txt
parente8452368cfee3395be199ce75638e7f730a97e21 (diff)
downloadmpv-3145bff020c1ac789d680452aa38c3f50f3be098.tar.bz2
mpv-3145bff020c1ac789d680452aa38c3f50f3be098.tar.xz
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
Diffstat (limited to 'DOCS/tech/code-documentation.txt')
-rw-r--r--DOCS/tech/code-documentation.txt124
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.
+
+