Add new Style Guides for languages used (and to be used) by project.

git-svn-id: svn://svn.berlios.de/openocd/trunk@1924 b42882b7-edfa-0310-969c-e2dbd0fdcd60

1 files changed, 212 insertions, 19 deletions

diff --git a/doc/manual/style.txt b/doc/manual/style.txt
index f6b6f63..545d7bb 100644
--- a/doc/manual/style.txt
+++ b/doc/manual/style.txt
@@ -1,19 +1,46 @@
-/** @page styleguide OpenOCD Coding C Style Guide
+/** @page styleguide Style Guides
 
-The following rules describe a formatting, naming, and other conventions
-that should be followed when writing or changing the OpenOCD C code.
-Many of the general rules should apply to OpenOCD's Jim/TCL code as well.
-
-The goals of this guide are:
-- to produce code that appears clean, consistent, and readable,
-- to allow developers to create patches that conform to a standard,
+The goals for each of these guides are:
+- to produce correct code that appears clean, consistent, and readable,
+- to allow developers to create patches that conform to a standard, and
 - to eliminate these issues as points of future contention.
-consistent.
 
 Some of these rules may be ignored in the spirit of these stated goals;
 however, such exceptions should be fairly rare.
 
-@section styleformat Formatting Rules
+The following style guides describe a formatting, naming, and other
+conventions that should be followed when writing or changing the OpenOCD
+code:
+
+- @subpage styletcl
+- @subpage stylec
+- @subpage styleperl
+- @subpage styleautotools
+
+In addition, the following style guides provide information for
+providing documentation, either as part of the C code or stand-alone.
+
+- @subpage styledoxygen
+- @subpage styletexinfo
+- @subpage stylelatex
+
+Feedback would be welcome to improve the OpenOCD guidelines.
+
+ */
+/** @page styletcl TCL Style Guide
+
+OpenOCD needs to expand its Jim/TCL Style Guide.
+
+Many of the guidelines listed on the @ref stylec page should apply to
+OpenOCD's Jim/TCL code as well.
+
+ */
+/** @page stylec C Style Guide
+
+This page contains guidelines for writing new C source code for the
+OpenOCD project.
+
+@section styleformat Formatting Guide
 
 - remove any trailing white space at the end of lines.
 - use TAB characters for indentation; do NOT use spaces.
@@ -23,7 +50,7 @@ however, such exceptions should be fairly rare.
 - remove any trailing empty lines at the end of source files
 - do not "comment out" code from the tree; instead, one should either:
   -# remove it entirely (Subversion can retrieve the old version), or
-  -# use an @c #if/#endif block.
+  -# use an @c \#if/\#endif block.
 
 Finally, try to avoid lines of code that are longer than than 72-80 columns:
 
@@ -74,20 +101,186 @@ int f(int x1, int x2)
 }
 @endcode
 
-@section styledoxygen Doxygen Rules
+ */
+/** @page styledoxygen Doxygen Style Guide
+
+The following sections provide guidelines for OpenOCD developers
+who wish to write Doxygen comments in the code or this manual.
+For an introduction to Doxygen documentation,
+see the @ref primerdoxygen.
+
+@section styledoxyblocks Doxygen Block Selection
 
-- use @c /// to for one-line documentation
-- for multiple lines, use a "block" style with one space
+Several different types of Doxygen comments can be used; often,
+one style will be the most appropriate for a specific context.
+The following guidelines provide developers with heuristics for
+selecting an appropriate form and writing consistent documentation
+comments.
+
+-# use @c /// to for one-line documentation of instances.
+-# for documentation requiring multiple lines, use a "block" style:
 @verbatim
 /**
- * @brief Short description.
- * Full description here.
- * @param foo Describe foo.
+ * @brief First sentence is short description.  Remaining text becomes
+ * the full description block, where "empty" lines start new paragraphs.
+ *
+ * One can make text appear in @a italics, @b bold, @c monospace, or
+ * in blocks such as the one in which this example appears in the Style
+ * Guide.  See the Doxygen Manual for the full list of commands.
+ *
+ * @param foo For a function, describe the parameters (e.g. @a foo). 
+ * @returns The value(s) returned, or possible error conditions.
  */
 @endverbatim
-- if the total line length will be less than 72 columns, then
+  -# The block should start on the line following the opening @c /**.
+  -# The end of the block, \f$*/\f$, should also be on its own line.
+  -# Every line in the block should have a @c '*' in-line with its start:
+    - A leading space is required to align the @c '*' with the @c /** line.
+    - A single "empty" line should separate the function documentation
+      from the block of parameter and return value descriptions.
+    - Except to separate paragraphs of documentation, other extra
+      "empty" lines should be removed from the block.
+  -# Only single spaces should be used; do @b not add mid-line indentation.
+-# If the total line length will be less than 72-80 columns, then
   - The @c /**< form can be used on the same line.
   - This style should be used sparingly; the best use is for fields:
-    - @code int field /**< field description */ @endcode
+    @code int field; /**< field description */ @endcode
+
+@section styledoxyall Doxygen Style Guide
+
+The following guidelines apply to all Doxygen comment blocks:
+
+-# Use the @c '\@cmd' form for all doxygen commands (do @b not use @c '\\cmd').
+-# Use symbol names such that Doxygen automatically creates links:
+  -# @c function_name() can be used to reference functions
+    (e.g. flash_set_dirty()).
+  -# @c struct_name::member_name should be used to reference structure
+    fields in the documentation (e.g. @c flash_driver_s::name).
+  -# URLS get converted to markup automatically, without any extra effort.
+  -# new pages can be linked into the heirarchy by using the @c \@subpage
+    command somewhere the page(s) under which they should be linked:
+  -# use @c \@ref in other contexts to create links to pages and sections.
+-# Use good Doxygen mark-up:
+  -# '\@a' (italics) should be used to reference parameters (e.g. <i>foo</i>).
+  -# '\@b' (bold) should be used to emphasizing <b>single</b> words.
+  -# '\@c' (monospace) should be used with <code>file names</code> and
+  <code>code symbols</code>, so they appear visually distinct from
+  surrounding text.
+  -# To mark-up multiple words, the HTML alternatives must be used.
+-# Two spaces should be used when nesting lists; do @b not use '\\t' in lists.
+-# Code examples provided in documentation must conform to the Style Guide.
+
+@section styledoxytext Doxygen Text Inputs
+
+In addition to the guidelines in the preceding sections, the following
+additional style guidelines should be considered when writing
+documentation as part of standalone text files:
+
+-# Text files must contain Doxygen at least one comment block:
+  -# Documentation should begin in the first column (except for nested lists).
+  -# Do NOT use the @c '*' convention that must be used in the source code.
+-# Each file should contain at least one @c \@page block.
+  -# Each new page should be listed as a \@subpage in the \@page block
+  of the page that should serve as its parent.
+  -# Large pages should be structure in parts using meaningful \@section
+  and \@subsection commands.
+-# Include a @c \@file block at the end of each Doxygen @c .txt file to
+  document its contents:
+  - Doxygen creates such pages for files automatically, but no content
+    will appear on them for those that only contain manual pages.
+  - The \@file block should provide useful meta-documentation to assist
+    techincal writers; typically, a list of the pages that it contains.
+  - For example, the @ref styleguide exists in @c doc/manual/style.txt,
+    which contains a reference back to itself.
+-# The \@file and \@page commands should begin on the same line as
+   the start of the Doxygen comment:
+@verbatim
+/** @page pagename Page Title
+
+Documentation for the page.
+
+ */
+/** @file
+
+This file contains the @page page.
+
+ */
+@endverbatim
+
+For an example, the Doxygen source for this Style Guide can be found in
+@c doc/manual/style.txt, alongside other parts of The Manual.  
+
+ */
+/** @page styletexinfo Texinfo Style Guide
+
+This page needs to provide style guidelines for Texinfo, the mark-up
+language used by The Guide for OpenOCD Users.
+
+ */
+/** @page stylelatex LaTeX Style Guide
+
+This page needs to provide style guidelines for using LaTeX, the
+typesetting language used by The References for OpenOCD Hardware.
+Likewise, the @ref primerlatex for using this guide needs to be completed.
+
+ */
+/** @page styleperl Perl Style Guide
+
+This page provides some style guidelines for using Perl, a scripting
+language used by several small tools in the tree:
+
+-# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and 
+   @c .pm for modules)
+-# Pass files as script parameters or piped as input:
+  - Do NOT code paths to files in the tree, as this breaks out-of-tree builds.
+  - If you must, then you must also use an automake rule to create the script.
+-# use @c '#!/usr/bin/perl' as the first line of Perl scripts.
+-# always <code>use strict</code> and <code>use warnings</code>
+-# invoke scripts indirectly in Makefiles or other scripts:
+@code
+perl script.pl
+@endcode
+
+Maintainers must also be sure to follow additional guidelines:
+-# Ensure that Perl scripts are committed as executables:
+  - Use "<code>chmod +x script.pl</code>"
+    @a before using "<code>svn add script.pl</code>", or
+  - Use "<code>svn ps svn:executable '*' script.pl</code>"
+    @a after using "<code>svn add script.pl</code>".
+
+ */
+/** @page styleautotools Autotools Style Guide
+
+This page contains style guidelines for the OpenOCD autotools scripts.
+
+The following guidelines apply to the @c configure.in file:
+- Better guidelines need to be developed, but until then...
+- Use good judgement.
+
+The following guidelines apply to @c Makefile.am files:
+-# When assigning variables with long lists of items:
+  -# Separate the values on each line to make the files "patch friendly":
+@code
+VAR = \
+	value1 \
+	value2 \
+	...
+	value9 \
+	value10
+@endcode
+ */
+/** @file
+
+This file contains the @ref styleguide pages.  The @ref styleguide pages
+include the following Style Guides for their respective code and
+documentation languages:
+
+- @ref styletcl
+- @ref stylec
+- @ref styledoxygen
+- @ref styletexinfo
+- @ref stylelatex
+- @ref styleperl
+- @ref styleautotools
 
  */