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 User's 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's 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 When you add a new command, driver, or driver option, it needs to be
  40 documented in the User's Guide.  Use the existing documentation for
  41 models, but feel free to make better use of Texinfo mechanisms.  See
  42 the Texinfo web site for the Texinfo manual and more information.
  43
  44 OpenOCD style guidelines for Texinfo documentation can be found on the
  45 @ref styletexinfo page.
  46
  47  */
  48 /** @page primerlatex LaTeX Primer
  49
  50 The OpenOCD project provides a number of reference guides using the
  51 LaTeX typesetting language.
  52
  53 - OpenOCD Quick Reference Sheets
  54 - OpenOCD Hardware Reference Guides
  55
  56 These documents have not yet been produced, so this Primer serves as
  57 a placeholder to describe how they are created and can be extended.
  58 The same holds true for the @ref stylelatex page.
  59
  60  */
  61 /** @page primerdoxygen Doxygen Primer
  62
  63 Doxygen-style comments are used to provide documentation in-line with
  64 the OpenOCD source code.  These comments are used to document functions,
  65 variables, structs, enums, fields, and everything else that might need
  66 to be documented for developers.  Additional files containing comments
  67 that supplement the code comments in order to provide complete developer
  68 documentation.
  69
  70 Even if you already know Doxygen, please read this Primer to learn
  71 how OpenOCD developers already use Doxygen features in the project tree.
  72 For more information about OpenOCD's required style for using Doxygen,
  73 see the @ref styledoxygen page and look at existing documentation in the
  74 @c doc/manual tree.
  75
  76 @section primerdoxytext Doxygen Input Files
  77
  78 Doxygen has been configured parse all of the C source code files (*.c
  79 and *.h) in @c src/ in order to produce a complete reference of all
  80 OpenOCD project symbols.  In addition to the source code files, other
  81 files will also be scanned for comment blocks; some are referenced
  82 explicitly by the @c INPUT variable in the Doxygen configuration file.
  83
  84 By default, the Doxygen configuration enables a "full" set of features,
  85 including generation of dependency graphs (using the GraphViz package).
  86 These features may be disabled by editing the @c Doxyfile.in file at the
  87 top of the project tree; the configuration file includes comments that
  88 provide detailed documentation for each option.
  89
  90 To support out-of-tree building of the documentation, the @c Doxyfile.in
  91 @c INPUT values will have all instances of the string @c "@srcdir@"
  92 replaced with the current value of the make variable
  93 <code>$(srcdir)</code>.  The Makefile uses a rule to convert
  94 @c Doxyfile.in into the @c Doxyfile used by <code>make doxygen</code>.
  95
  96 @section primerdoxyoocd OpenOCD Input Files
  97
  98 OpenOCD uses the @c INPUT mechanism to include additional documentation to
  99 provide The Manual for OpenOCD Developers.  These extra files contain
 100 high-level information intended to supplement the relatively low-level
 101 documentation that gets extracted from the source code comments.
 102
 103 OpenOCD's Doxygen configuration file will search for all @c .txt files
 104 that can be found under the @c doc/manual directory in the project tree.
 105 New files containing valid Doxygen markup that are placed in or under
 106 that directory will be detected and included in The Manual automatically.
 107
 108 @section primerdoxyman Doxygen Reference Manual
 109
 110 The full documentation for Doxygen can be referenced on-line at the project
 111 home page: http://www.doxygen.org/index.html.  In HTML versions of this
 112 document, an image with a link to this site appears in the page footer.
 113
 114 */
 115 /** @file
 116
 117 This file contains the Doxygen source code for the @ref primerdocs.
 118 The @ref primerdocs page also contains the following sections:
 119
 120 - @ref primertexinfo
 121 - @ref primerlatex
 122 - @ref primerdoxygen
 123
 124  */