doc/manual/primer/docs.txt

   1 /** @page primerdocs OpenOCD Documentation Primers
   2
   3 This page provides an introduction to OpenOCD's documentation processes.
   4
   5 OpenOCD presently produces several kinds of documentation:
   6 - The Guide:
   7   - Focuses on using the OpenOCD software.
   8   - Details the installation, usage, and customization.
   9   - Provides descriptions of public Jim/TCL script commands.
  10   - Written using GNU texinfo.
  11   - Created with 'make pdf' or 'make html'.
  12   - See @subpage primertexinfo and @ref styletexinfo.
  13 - The References: (as proposed)
  14   - Focuses on using specific hardware with OpenOCD.
  15   - Details the supported interfaces, chips, boards, and targets.
  16   - Provides overview, usage, reference, and FAQ for each device.
  17   - Written using LaTeX language with custom macros.
  18   - Created with 'make references'.
  19   - See @subpage primerlatex and @ref stylelatex.
  20 - The Manual:
  21   - Focuses on developing the OpenOCD software.
  22   - Details the architecutre, driver interfaces, and processes.
  23   - Provides "full" coverage of C source code (work-in-progress).
  24   - Written using Doxygen C language conventions (i.e. in comments).
  25   - Created with 'make doxygen'.
  26   - See @subpage primerdoxygen and @ref styledoxygen.
  27
  28 The following sections provide more information for anyone that wants to
  29 contribute new or updated documentation to the OpenOCD project.
  30
  31  */
  32 /** @page primertexinfo Texinfo Primer
  33
  34 The OpenOCD User Guide presently exists entirely within the
  35 doc/openocd.texi document.  That file contains documentation with
  36 mark-up suitable for being parsed by the GNU Texinfo utilities
  37 (http://www.gnu.org/software/texinfo/).
  38
  39 This section needs to be expanded to provide an overview to new
  40 developers.
  41
  42 OpenOCD style guidelines for Texinfo documentation can be found on the
  43 @ref styletexinfo page.
  44
  45  */
  46 /** @page primerlatex LaTeX Primer
  47
  48 The OpenOCD project provides a number of reference guides using the
  49 LaTeX typesetting language.
  50
  51 - OpenOCD Quick Reference Sheets
  52 - OpenOCD Hardware Reference Guides
  53
  54 These documents have not yet been produced, so this Primer serves as
  55 a placeholder to describe how they are created and can be extended.
  56 The same holds true for the @ref stylelatex page.
  57
  58  */
  59 /** @page primerdoxygen Doxygen Primer
  60
  61 Doxygen-style comments are used to provide documentation in-line with
  62 the OpenOCD source code.  These comments are used to document functions,
  63 variables, structs, enums, fields, and everything else that might need
  64 to be documented for developers.  Additional files containing comments
  65 that supplement the code comments in order to provide complete developer
  66 documentation.
  67
  68 Even if you already know Doxygen, please read this Primer to learn
  69 how OpenOCD developers already use Doxygen features in the project tree.
  70 For more information about OpenOCD's required style for using Doxygen,
  71 see the @ref styledoxygen page and look at existing documentation in the
  72 @c doc/manual tree.
  73
  74 @section primerdoxytext Doxygen Input Files
  75
  76 Doxygen has been configured parse all of the C source code files (*.c
  77 and *.h) in @c src/ in order to produce a complete reference of all
  78 OpenOCD project symbols.  In addition to the source code files, other
  79 files will also be scanned for comment blocks; some are referenced
  80 explicitly by the @c INPUT variable in the Doxygen configuration file.
  81
  82 By default, the Doxygen configuration enables a "full" set of features,
  83 including generation of dependency graphs (using the GraphViz package).
  84 These features may be disabled by editing the @c Doxyfile.in file at the
  85 top of the project tree; the configuration file includes comments that
  86 provide detailed documentation for each option.
  87
  88 To support out-of-tree building of the documentation, the @c Doxyfile.in
  89 @c INPUT values will have all instances of the string @c "@srcdir@"
  90 replaced with the current value of the make variable
  91 <code>$(srcdir)</code>.  The Makefile uses a rule to convert
  92 @c Doxyfile.in into the @c Doxyfile used by <code>make doxygen</code>.
  93
  94 @section primerdoxyoocd OpenOCD Input Files
  95
  96 OpenOCD uses the @c INPUT mechanism to include additional documentation to
  97 provide The Manual for OpenOCD Developers.  These extra files contain
  98 high-level information intended to supplement the relatively low-level
  99 documentation that gets extracted from the source code comments.
 100
 101 OpenOCD's Doxygen configuration file will search for all @c .txt files
 102 that can be found under the @c doc/manual directory in the project tree.
 103 New files containing valid Doxygen markup that are placed in or under
 104 that directory will be detected and included in The Manual automatically.
 105
 106 @section primerdoxyman Doxygen Reference Manual
 107
 108 The full documentation for Doxygen can be referenced on-line at the project
 109 home page: http://www.doxygen.org/index.html.  In HTML versions of this
 110 document, an image with a link to this site appears in the page footer.
 111
 112 */
 113 /** @file
 114
 115 This file contains the Doxygen source code for the @ref primerdocs.
 116 The @ref primerdocs page also contains the following sections:
 117
 118 - @ref primertexinfo
 119 - @ref primerlatex
 120 - @ref primerdoxygen
 121
 122  */