Commit skeleton files for high-level developer manual using doxygen.

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

diff --git a/Doxyfile b/Doxyfile
index f75d72fe98ff3ae75c14d4d9371385de19fcd67c..fbc39ccbc214fa06d891f79675edb9eaec191cc5 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -564,7 +564,9 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = config.h src
+INPUT                  = doc/manual \
+                         src \
+                         config.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -582,7 +584,8 @@ INPUT_ENCODING         = UTF-8
 # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90
 
 FILE_PATTERNS          = *.h \
-                         *.c
+                         *.c \
+                        *.txt
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
 # should be searched for input files as well. Possible values are YES and NO.

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6bc2ea88039950e3bd4680037aefaca5f4ecc6a0..e85ed75207f1eb5b31d7bb8da7051fcac1b1f4e1 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -3,4 +3,8 @@ openocd_TEXINFOS = fdl.texi
 man_MANS = openocd.1
 EXTRA_DIST = openocd.1
 
+dist-hook:
+       mkdir $(distdir)/manual
+       cp -p $(srcdir)/manual/*.txt $(distdir)/manual
+
 MAINTAINERCLEANFILES = Makefile.in mdate-sh texinfo.tex

diff --git a/doc/manual/app.txt b/doc/manual/app.txt
new file mode 100644 (file)
index 0000000..989e6e6
--- /dev/null
+++ b/doc/manual/app.txt
@@ -0,0 +1,9 @@
+/** @page appdocs OpenOCD Application APIs
+
+The top-level APIs in the OpenOCD library allow applications to integrate
+all of the low-level functionality using a set of simple function calls.
+
+These function calls do not exist in a re-usable form, but
+contributions to create and document them will be welcome.
+
+ */

diff --git a/doc/manual/flash.txt b/doc/manual/flash.txt
new file mode 100644 (file)
index 0000000..dbc4b94
--- /dev/null
+++ b/doc/manual/flash.txt
@@ -0,0 +1,35 @@
+/** @page flashdocs OpenOCD Flash APIs
+
+OpenOCD provides its Flash APIs for developers to support different
+types of flash devices, some of which are built-in to target devices
+while others may be connected via standard memory interface (e.g. CFI,
+FMI, etc.).
+
+The Flash module provides the following APIs:
+
+  - @subpage flashcfi 
+  - @subpage flashnand
+  - @subpage flashtarget
+
+This section needs to be expanded.
+
+*/
+
+
+/** @page flashcfi OpenOCD CFI Flash API
+
+This section needs to be expanded to describe OpenOCD's CFI Flash API.
+
+*/
+
+/** @page flashnand OpenOCD NAND Flash API
+
+This section needs to be expanded to describe OpenOCD's NAND Flash API.
+
+*/
+
+/** @page flashtarget OpenOCD Target Flash API
+
+This section needs to be expanded to describe OpenOCD's Target Flash API.
+
+*/

diff --git a/doc/manual/helper.txt b/doc/manual/helper.txt
new file mode 100644 (file)
index 0000000..91bf2d5
--- /dev/null
+++ b/doc/manual/helper.txt
@@ -0,0 +1,48 @@
+/** @page helperdocs OpenOCD Helper APIs
+
+OpenOCD uses several low-level APIs as the foundation for high-level APIs:
+
+  - @subpage helperporting
+  - @subpage helperjim
+  - @subpage helpercommand
+  - @subpage helperlogging
+  - @subpage helperbuffers
+
+This section needs to be expanded.
+
+ */
+
+/** @page helperporting OpenOCD Types/Portability APIs
+
+This section needs to be expanded to describe OpenOCD's type and
+portability API.
+
+ */
+
+/** @page helperjim OpenOCD Jim API
+
+The Jim API provides access to a small-footprint TCL implementation.
+
+Visit http://jim.berlios.de/ for more information on Jim.
+
+This section needs to be expanded to describe OpenOCD's Jim API.
+
+ */
+
+/** @page helpercommand OpenOCD Command API
+
+This section needs to be expanded to describe OpenOCD's Command API.
+
+ */
+
+/** @page helperlogging OpenOCD Logging API
+
+This section needs to be expanded to describe OpenOCD's Logging API.
+
+ */
+
+/** @page helperbuffers OpenOCD Byte Buffer API
+
+This section needs to be expanded to describe OpenOCD's Byte Buffer API.
+
+ */

diff --git a/doc/manual/jtag.txt b/doc/manual/jtag.txt
new file mode 100644 (file)
index 0000000..b2e5b19
--- /dev/null
+++ b/doc/manual/jtag.txt
@@ -0,0 +1,39 @@
+/** @page jtagdocs OpenOCD JTAG APIs
+
+This document contains @subpage jtagprimer, which introduces the
+IEEE JTAG interface.
+
+The OpenOCD JTAG library API covers several functional areas:
+
+  - @subpage jtagcable
+  - @subpage jtagtap
+  - @subpage jtagmdriver
+  - @subpage jtagdriver
+
+This section needs to be expanded.
+
+ */
+
+/** @page jtagcable OpenOCD JTAG Cable API
+
+This section needs to be expanded.
+
+ */
+
+/** @page jtagtap OpenOCD JTAG TAP API
+
+This section needs to be expanded.
+
+ */
+
+/** @page jtagmdriver OpenOCD JTAG Interface API
+
+This section needs to be expanded.
+
+ */
+
+/** @page jtagdriver OpenOCD JTAG Driver API
+
+This section needs to be expanded.
+
+ */

diff --git a/doc/manual/main.txt b/doc/manual/main.txt
new file mode 100644 (file)
index 0000000..9a476e3
--- /dev/null
+++ b/doc/manual/main.txt
@@ -0,0 +1,45 @@
+/** @mainpage OpenOCD Reference Manual
+
+The @ref primer page provides introductory materials for new developers.
+
+The @ref oocd page explains how the code has been organized into layers
+of APIs and gives an overview of how they fit together.
+ 
+ */
+
+/** @page oocd OpenOCD Architecture
+
+The OpenOCD library consists of several APIs that build together to
+provide the support functionality.  The following list shows how these
+modules are stacked in the current implementation (from bottom to top):
+
+- @subpage helperdocs
+  - @ref helperporting
+  - @ref helperjim
+  - @ref helpercommand
+  - @ref helperlogging
+- @subpage jtagdocs
+  - @ref jtagcable
+  - @ref jtagtap
+  - @ref jtagmdriver
+  - @ref jtagdriver
+- @subpage targetdocs
+  - @ref targetarm
+  - @ref targetnotarm
+  - @ref targetregister
+  - @ref targetimage
+  - @ref targettrace
+- @subpage flashdocs
+  - @ref flashcfi
+  - @ref flashnand
+  - @ref flashtarget
+- @subpage serverdocs
+  - @ref servergdb
+  - @ref servertelnet
+  - @ref serverhttp
+- @subpage appdocs
+
+Obviously, there are some nuances to the stack that are not shown by
+this linear list of layers.
+
+ */

diff --git a/doc/manual/server.txt b/doc/manual/server.txt
new file mode 100644 (file)
index 0000000..2379a93
--- /dev/null
+++ b/doc/manual/server.txt
@@ -0,0 +1,30 @@
+/** @page serverdocs OpenOCD Server APIs
+
+OpenOCD provides support for implementing different types of servers.
+Presently, the following servers have APIs that can be used.
+
+  - @subpage servergdb
+  - @subpage servertelnet
+  - @subpage serverhttp
+
+This section needs to be expanded.
+
+ */
+
+/** @page servergdb OpenOCD GDB Server API
+
+This section needs to be expanded.
+
+ */
+
+/** @page servertelnet OpenOCD Telnet Server API
+
+This section needs to be expanded.
+
+ */
+
+/** @page serverhttp OpenOCD HTTP Server API
+
+This section needs to be expanded.
+
+ */

diff --git a/doc/manual/target.txt b/doc/manual/target.txt
new file mode 100644 (file)
index 0000000..26f7708
--- /dev/null
+++ b/doc/manual/target.txt
@@ -0,0 +1,51 @@
+/** @page targetdocs OpenOCD Target APIs
+
+OpenOCD provides its Target APIs to allow developers to provide trace and
+debugging support for specific device targets.  These primarily consist of
+ARM cores, but other types have been supported.  New targets should be
+developed by following or using these APIs.
+
+The Target Support module contains APIs that cover several functional areas:
+
+  - @subpage targetarm
+  - @subpage targetnotarm
+  - @subpage targetregister
+  - @subpage targetimage
+  - @subpage targettrace
+
+This section needs to be expanded.
+
+*/
+
+/** @page targetarm OpenOCD ARM Targets
+
+This section needs to describe OpenOCD's ARM target support.
+
+ */
+
+/** @page targetnotarm OpenOCD Non-ARM Targets
+
+This section needs to describe OpenOCD's non-ARM target support.
+
+ */
+
+/** @page targetregister OpenOCD Target Register API
+
+This section needs to describe OpenOCD's Target Register API, as
+provided by 'src/target/register.h'.
+
+ */
+
+/** @page targetimage OpenOCD Target Image API
+
+This section needs to describe OpenOCD's Target Image API, as provided
+by 'src/target/image.h'.
+
+ */
+
+/** @page targettrace OpenOCD Target Trace API
+
+This section needs to describe OpenOCD's Target Trace API, as provided
+by 'src/target/trace.h'.
+
+ */