You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

125 lines
5.1 KiB

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