diff options
Diffstat (limited to 'doc/manual/primer/docs.txt')
-rw-r--r-- | doc/manual/primer/docs.txt | 124 |
1 files changed, 0 insertions, 124 deletions
diff --git a/doc/manual/primer/docs.txt b/doc/manual/primer/docs.txt deleted file mode 100644 index 504da79..0000000 --- a/doc/manual/primer/docs.txt +++ /dev/null @@ -1,124 +0,0 @@ -/** @page primerdocs OpenOCD Documentation Primers - -This page provides an introduction to OpenOCD's documentation processes. - -OpenOCD presently produces several kinds of documentation: -- The User's Guide: - - Focuses on using the OpenOCD software. - - Details the installation, usage, and customization. - - Provides descriptions of public Jim/TCL script commands. - - Written using GNU texinfo. - - Created with 'make pdf' or 'make html'. - - See @subpage primertexinfo and @ref styletexinfo. -- The References: (as proposed) - - Focuses on using specific hardware with OpenOCD. - - Details the supported interfaces, chips, boards, and targets. - - Provides overview, usage, reference, and FAQ for each device. - - Written using LaTeX language with custom macros. - - Created with 'make references'. - - See @subpage primerlatex and @ref stylelatex. -- The Manual: - - Focuses on developing the OpenOCD software. - - Details the architecutre, driver interfaces, and processes. - - Provides "full" coverage of C source code (work-in-progress). - - Written using Doxygen C language conventions (i.e. in comments). - - Created with 'make doxygen'. - - See @subpage primerdoxygen and @ref styledoxygen. - -The following sections provide more information for anyone that wants to -contribute new or updated documentation to the OpenOCD project. - - */ -/** @page primertexinfo Texinfo Primer - -The OpenOCD User's Guide presently exists entirely within the -doc/openocd.texi document. That file contains documentation with -mark-up suitable for being parsed by the GNU Texinfo utilities -(http://www.gnu.org/software/texinfo/). - -When you add a new command, driver, or driver option, it needs to be -documented in the User's Guide. Use the existing documentation for -models, but feel free to make better use of Texinfo mechanisms. See -the Texinfo web site for the Texinfo manual and more information. - -OpenOCD style guidelines for Texinfo documentation can be found on the -@ref styletexinfo page. - - */ -/** @page primerlatex LaTeX Primer - -The OpenOCD project provides a number of reference guides using the -LaTeX typesetting language. - -- OpenOCD Quick Reference Sheets -- OpenOCD Hardware Reference Guides - -These documents have not yet been produced, so this Primer serves as -a placeholder to describe how they are created and can be extended. -The same holds true for the @ref stylelatex page. - - */ -/** @page primerdoxygen Doxygen Primer - -Doxygen-style comments are used to provide documentation in-line with -the OpenOCD source code. These comments are used to document functions, -variables, structs, enums, fields, and everything else that might need -to be documented for developers. Additional files containing comments -that supplement the code comments in order to provide complete developer -documentation. - -Even if you already know Doxygen, please read this Primer to learn -how OpenOCD developers already use Doxygen features in the project tree. -For more information about OpenOCD's required style for using Doxygen, -see the @ref styledoxygen page and look at existing documentation in the -@c doc/manual tree. - -@section primerdoxytext Doxygen Input Files - -Doxygen has been configured parse all of the C source code files (*.c -and *.h) in @c src/ in order to produce a complete reference of all -OpenOCD project symbols. In addition to the source code files, other -files will also be scanned for comment blocks; some are referenced -explicitly by the @c INPUT variable in the Doxygen configuration file. - -By default, the Doxygen configuration enables a "full" set of features, -including generation of dependency graphs (using the GraphViz package). -These features may be disabled by editing the @c Doxyfile.in file at the -top of the project tree; the configuration file includes comments that -provide detailed documentation for each option. - -To support out-of-tree building of the documentation, the @c Doxyfile.in -@c INPUT values will have all instances of the string @c "@srcdir@" -replaced with the current value of the make variable -<code>$(srcdir)</code>. The Makefile uses a rule to convert -@c Doxyfile.in into the @c Doxyfile used by <code>make doxygen</code>. - -@section primerdoxyoocd OpenOCD Input Files - -OpenOCD uses the @c INPUT mechanism to include additional documentation to -provide The Manual for OpenOCD Developers. These extra files contain -high-level information intended to supplement the relatively low-level -documentation that gets extracted from the source code comments. - -OpenOCD's Doxygen configuration file will search for all @c .txt files -that can be found under the @c doc/manual directory in the project tree. -New files containing valid Doxygen markup that are placed in or under -that directory will be detected and included in The Manual automatically. - -@section primerdoxyman Doxygen Reference Manual - -The full documentation for Doxygen can be referenced on-line at the project -home page: http://www.doxygen.org/index.html. In HTML versions of this -document, an image with a link to this site appears in the page footer. - -*/ -/** @file - -This file contains the Doxygen source code for the @ref primerdocs. -The @ref primerdocs page also contains the following sections: - -- @ref primertexinfo -- @ref primerlatex -- @ref primerdoxygen - - */ |