[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Cp-tools-discuss] Documentation updates
|
From: |
Mark Wielaard |
|
Subject: |
[Cp-tools-discuss] Documentation updates |
|
Date: |
Sat, 05 Feb 2005 18:09:35 +0100 |
Hi,
Here are some small documentation updates.
2005-02-05 Mark Wielaard <address@hidden>
* README: Add Java2xhtml notice.
Expand documentation, add debug and xml doclet description.
Put Installation and Usage before Missing Features.
Add command line options to Usage section.
Move kaffe jar problem to TROUBLESHOOTING.
* TROUBLESHOOTING: Add kaffe jar problem.
* src/gnu/classpath/tools/gjdoc/Main.java (usage):
Make sure all lines are < 80 characters wide.
Comment? OK to commit?
Cheers,
Mark
Index: README
===================================================================
RCS file: /cvsroot/classpath/gjdoc/README,v
retrieving revision 1.12
diff -u -r1.12 README
--- README 4 Feb 2005 17:41:16 -0000 1.12
+++ README 5 Feb 2005 17:07:13 -0000
@@ -1,5 +1,5 @@
- gjdoc - A doclet driver for the Java platform.
+ gjdoc - A documentation generation framework for java source files.
Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation
This program is free software; you can redistribute it and/or modify
@@ -16,10 +16,15 @@
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ Includes Java2xhtml distributed under the same terms with the following
+ notice: Copyright (C) 2003 Shayne Steele
+ License and warranty are under the terms of the GNU General Public License
+ Version 2.0. See http://www.gnu.org for license and warranty details.
+
gjdoc
=====
-Doclet driver with standard Doclet.
+Documentation generation framework for java source files.
Version 0.7.1
(C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation
@@ -27,40 +32,48 @@
Released under the GNU General Public License (GPL).
1. Overview
-2. Missing Features
-3. Installation
-4. Usage
+2. Installation
+3. Usage
+4. Missing Features
5. Feedback
1. Overview
------------------------------------------------------------------------------
-Gjdoc is a drop-in replacement for the command line tool `javadoc'
-shipped with Sun's JDK.
-
-Gjdoc's current version implements all features of Sun's Javadoc 1.4.
-It should be command-line compatible and provide a compatible Doclet
-API.
-
-However, in contrast to Javadoc, `gjdoc' does not perfom syntax
-checking on the supplied sources. If necessary, use something like
-`jikes +B' for checking the sources beforehand.
+Gjdoc is a documentation framework for generating documentation in
+various formats from java source file. It is both a drop-in
+replacement for the traditional command line tool `javadoc' and
+provides an interface for inspection of and generation of different
+output for java source packages, classes, methods and fields.
+
+Gjdoc's current version implements all features of the traditional
+javadoc tool up to version 1.4. It should be fully command-line
+compatible and provides a compatible Doclet API (com.sun.javadoc).
+
+However, in contrast to Javadoc, `gjdoc' does not perfom syntax
+checking on the supplied sources. If necessary, use a real compiler
+like `gcj -fsyntax-only` or `jikes +B' for checking the sources
+beforehand.
The gjdoc package ships with a standard doclet for generating HTML
-output.
+output (the default).
+
+A debug doclet which just prints (not yet) all information to
+System.out and which can be used to explore the doclet interface.
+(enabled by -doclet gnu.classpath.tools.doclets.debugdoclet.DebugDoclet)
+
+And doclet that generates output in XML format, which can then be
+postprocessed into other formats with xslt tools like xsltproc or the
+javax.xml.transform package of GNU JAXP and/or GNU Classpath.
+(Only available when configured with --enable-xmldoclet and enabled by
+ -doclet gnu.classpath.tools.doclets.xmldoclet.Driver)
This tool is a part of GNU Classpath-tools.
See http://www.gnu.org/software/classpath/cp-tools/
-2. Missing Features
-------------------------------------------------------------------------------
-
-- No Javadoc 1.5 functionality.
- For example, the new 1.5 language features are not supported.
-
-3. Installation
+2. Installation
------------------------------------------------------------------------------
Generic installation instructions apply:
@@ -69,23 +82,98 @@
See INSTALL for further details.
Gjdoc is known to build with GNU GCJ 4.0 and jikes 1.21. It is known
-to run on GCJ 4.0, kaffe x.x and jamvm 1.2.3.
+to run on GCJ 4.0, kaffe (CVS of February 5 2005) and jamvm 1.2.3.
You will also need ANTLR 2.7.1 or better installed. See http://antlr.org/.
-There are known problems with the current version of kaffe's jar tool
-(as of Feburary 2005) which is the default on some platforms. Use the
-JAR environment variable to specify a different jar tool if the build
-hangs while assembling the jar file or if you get the error message
-"FATAL ERROR: No more room for local references".
+For a couple of know build and runtime problems please see the file
+TROUBLESHOOTING.
-4. Usage
+3. Usage
------------------------------------------------------------------------------
-Run `gjdoc' without parameters for further usage information.
+USAGE: gjdoc [options] [packagenames] [sourcefiles] address@hidden
+
+ --version Show version information and exit
+ -overview <file> Read overview documentation from HTML file
+ -public Include only public classes and members
+ -protected Include protected and public classes and members
+ This is the default
+ -package Include package/protected/public classes and members
+ -private Include all classes and members
+ -help Show this information
+ -doclet <class> Doclet class to use for generating output
+ -docletpath <classpath> Specifies the search path for the doclet and
+ dependencies
+ -source <release> Provide source compatibility with specified
+ release (1.4 to handle assertion)
+ -sourcepath <pathlist> Where to look for source files
+ -verbose Output messages about what Gjdoc is doing [ignored]
+ -quiet Do not print non-error and non-warning messages
+ -locale <name> Locale to be used, e.g. en_US or en_US_WIN [ignored]
+ -encoding <name> Source file encoding name
+ -breakiterator Compute first sentence with BreakIterator
+ -classpath Set the path used for loading auxilliary classes
+
+Gjdoc extension options:
+ -licensetext Include license text from source files
+
+Standard doclet options:
+ -d Set target directory
+ -use Includes the 'Use' page for each documented class
+ and package
+ -version Includes the '@version' tag
+ -author Includes the '@author' tag
+ -splitindex Splits the index file into multiple files
+ -windowtitle <text> Browser window title
+ -doctitle <text> Title near the top of the overview summary file
+ (html allowed)
+ -title <text> Title for this set of API documentation
+ (deprecated, -doctitle should be used instead)
+ -header <text> Text to include in the top navigation bar
+ (html allowed)
+ -footer <text> Text to include in the bottom navigation bar
+ (html allowed)
+ -bottom <text> Text to include at the bottom of each output file
+ (html allowed)
+ -link <extdoc URL> Link to external generated documentation at URL
+ -linkoffline <extdoc URL> <packagelistLoc>
+ Link to external generated documentation for
+ the specified package-list
+ -linksource Creates an HTML version of each source file
+ -group <groupheading> <packagepattern:packagepattern:...>
+ Separates packages on the overview page into groups
+ -nodeprecated Prevents the generation of any deprecated API
+ -nodeprecatedlist Prevents the generation of the file containing
+ the list of deprecated APIs and the link to the
+ navigation bar to that page
+ -nosince Omit the '@since' tag
+ -notree Do not generate the class/interface hierarchy page
+ -noindex Do not generate the index file
+ -nohelp Do not generate the HELP link
+ -nonavbar Do not generate the navbar, header and footer
+ -helpfile <filen> Path of an alternate help file
+ -stylesheetfile <file> Path of an alternate html stylesheet
+ -charset <IANACharset> Specifies the HTML charset
+ -docencoding <IANACharset>
+ Specifies the encoding of the generated HTML files
+ -tag <tagname>:Xaoptcmf:"<taghead>"
+ Enables gjdoc to interpret a custom tag
+ -taglet Adds a Taglet class to the map of taglets
+ -tagletpath Sets the CLASSPATH to load subsequent Taglets from
+ -subpackages <spkglist> List of subpackages to recursively load
+ -exclude <pkglist> List of packages to exclude
+ -docfilessubdirs Enables deep copy of 'doc-files' directories
+ -excludedocfilessubdir <name1:name2:...>
+ Excludes 'doc-files' subdirectories with a give
-More information coming soon.
+
+4. Missing Features
+------------------------------------------------------------------------------
+
+- No Javadoc 1.5 functionality.
+ For example, the new 1.5 language features are not supported.
5. Feedback
Index: TROUBLESHOOTING
===================================================================
RCS file: /cvsroot/classpath/gjdoc/TROUBLESHOOTING,v
retrieving revision 1.2
diff -u -r1.2 TROUBLESHOOTING
--- TROUBLESHOOTING 20 Dec 2004 21:27:52 -0000 1.2
+++ TROUBLESHOOTING 5 Feb 2005 17:07:14 -0000
@@ -2,7 +2,7 @@
Gjdoc Troubleshooting FAQ
=========================
-Last updated: 2004-12-11
+Last updated: 5 February 2005
When building and running Gjdoc there are several problems you can run
into at the time of this writing. Most of these stumbling blocks will
@@ -58,6 +58,19 @@
script. Otherwise, the build will use the jni.h header file that comes
with JDK instead of the one which belongs to gcj.
+-----
+
+Q: While generating the jar file the build just hangs/I get the
+following messeage while generating a jar file:
+"FATAL ERROR: No more room for local references".
+
+A: There are known problems with the current (CVS) version of kaffe's
+jar tool (as of Feburary 2005) which is the default on some
+platforms. Use the JAR environment variable to specify a different jar
+tool if the build hangs while assembling the jar file or if you get
+the above error message. The fastjar tool that comes with GCC is known
+to work.
+
Run-time Troubleshooting
Index: src/gnu/classpath/tools/gjdoc/Main.java
===================================================================
RCS file: /cvsroot/classpath/gjdoc/src/gnu/classpath/tools/gjdoc/Main.java,v
retrieving revision 1.54
diff -u -r1.54 Main.java
--- src/gnu/classpath/tools/gjdoc/Main.java 4 Feb 2005 17:41:16 -0000
1.54
+++ src/gnu/classpath/tools/gjdoc/Main.java 5 Feb 2005 17:07:14 -0000
@@ -1288,14 +1288,16 @@
+ " --version Show version information and exit\n"
+ " -overview <file> Read overview documentation from
HTML file\n"
+ " -public Include only public classes and
members\n"
- + " -protected Include protected and public classes
and members.\n"
- + " This is the default.\n"
+ + " -protected Include protected and public classes
and members\n"
+ + " This is the default\n"
+ " -package Include package/protected/public
classes and members\n"
+ " -private Include all classes and members\n"
+ " -help Show this information\n"
+ " -doclet <class> Doclet class to use for generating
output\n"
- + " -docletpath <classpath> Specifies the search path for the
doclet and dependencies\n"
- + " -source <release> Provide source compatibility with
specified release (1.4 to handle assertion)\n"
+ + " -docletpath <classpath> Specifies the search path for the
doclet and\n"
+ + " dependencies\n"
+ + " -source <release> Provide source compatibility with
specified\n"
+ + " release (1.4 to handle assertion)\n"
+ " -sourcepath <pathlist> Where to look for source files\n"
+ " -verbose Output messages about what Gjdoc is
doing [ignored]\n"
+ " -quiet Do not print non-error and
non-warning messages\n"
@@ -1303,46 +1305,61 @@
+ " -encoding <name> Source file encoding name\n"
+ " -breakiterator Compute first sentence with
BreakIterator\n"
+ " -classpath Set the path used for loading
auxilliary classes\n"
-
+ + "\n"
+ "Gjdoc extension options:\n"
- + " -licensetext Include license text from source
files\n"
-
+ + " -licensetext Include license text from source
files\n"
+ + "\n"
+ "Standard doclet options:\n"
+ " -d Set target directory\n"
- + " -use Includes the 'Use' page for each
documented class and package\n"
+ + " -use Includes the 'Use' page for each
documented class\n"
+ + " and package\n"
+ " -version Includes the '@version' tag\n"
+ " -author Includes the '@author' tag\n"
+ " -splitindex Splits the index file into multiple
files\n"
+ " -windowtitle <text> Browser window title\n"
- + " -doctitle <text> Title near the top of the overview
summary file (html allowed)\n"
- + " -title <text> Title for this set of API
documentation (deprecated, -doctitle should be used instead).\n"
- + " -header <text> Text to include in the top navigation
bar (html allowed)\n"
- + " -footer <text> Text to include in the bottom
navigation bar (html allowed)\n"
- + " -bottom <text> Text to include at the bottom of each
output file (html allowed)\n"
- + " -link <extdoc URL> Link to external javadoc-generated
documentation you want to link to\n"
- + " -linkoffline <extdoc URL> <packagelistLoc> Link to external
javadoc-generated documentation for the specified package-list\n"
+ + " -doctitle <text> Title near the top of the overview
summary file\n"
+ + " (html allowed)\n"
+ + " -title <text> Title for this set of API
documentation\n"
+ + " (deprecated, -doctitle should be used
instead)\n"
+ + " -header <text> Text to include in the top navigation
bar\n"
+ + " (html allowed)\n"
+ + " -footer <text> Text to include in the bottom
navigation bar\n"
+ + " (html allowed)\n"
+ + " -bottom <text> Text to include at the bottom of each
output file\n"
+ + " (html allowed)\n"
+ + " -link <extdoc URL> Link to external generated
documentation at URL\n"
+ + " -linkoffline <extdoc URL> <packagelistLoc>\n"
+ + " Link to external generated
documentation for\n"
+ + " the specified package-list\n"
+ " -linksource Creates an HTML version of each
source file\n"
- + " -group <groupheading> <packagepattern:packagepattern:...>
Separates packages on the overview page into groups\n"
+ + " -group <groupheading> <packagepattern:packagepattern:...>\n"
+ + " Separates packages on the overview
page into groups\n"
+ " -nodeprecated Prevents the generation of any
deprecated API\n"
- + " -nodeprecatedlist Prevents the generation of the file
containing the list of deprecated APIs and the link to the navigation bar to
that page\n"
+ + " -nodeprecatedlist Prevents the generation of the file
containing\n"
+ + " the list of deprecated APIs and the
link to the\n"
+ + " navigation bar to that page\n"
+ " -nosince Omit the '@since' tag\n"
+ " -notree Do not generate the class/interface
hierarchy page\n"
+ " -noindex Do not generate the index file\n"
+ " -nohelp Do not generate the HELP link\n"
+ " -nonavbar Do not generate the navbar, header
and footer\n"
- + " -helpfile <filename> Path of an alternate help file\n"
- + " -stylesheetfile <filename> Path of an alternate html
stylesheet\n"
+ + " -helpfile <filen> Path of an alternate help file\n"
+ + " -stylesheetfile <file> Path of an alternate html
stylesheet\n"
/* + " -serialwarn Generate compile time error for
missing '@serial' tags\n" */
- + " -charset <IANACharset> Specifies the HTML charset\n"
- + " -docencoding <IANACharset> Specifies the encoding of the
generated HTML files\n"
- + " -tag <tagname>:Xaoptcmf:\"<taghead>\" Enables gjdoc to
interpret a custom tag\n"
- + " -taglet Adds a Taglet class to the map of
taglets.\n"
- + " -tagletpath Sets the CLASSPATH to load subsequent
Taglets from.\n"
+ + " -charset <IANACharset> Specifies the HTML charset\n"
+ + " -docencoding <IANACharset>\n"
+ + " Specifies the encoding of the
generated HTML files\n"
+ + " -tag <tagname>:Xaoptcmf:\"<taghead>\"\n"
+ + " Enables gjdoc to interpret a custom
tag\n"
+ + " -taglet Adds a Taglet class to the map of
taglets\n"
+ + " -tagletpath Sets the CLASSPATH to load subsequent
Taglets from\n"
+ " -subpackages <spkglist> List of subpackages to recursively
load\n"
+ " -exclude <pkglist> List of packages to exclude\n"
+ " -docfilessubdirs Enables deep copy of 'doc-files'
directories\n"
- + " -excludedocfilessubdir <name1:name2:...> Excludes
'doc-files' subdirectories with a give name\n"
- + " -noqualifier all|<packagename1:packagename2:...> Do not
qualify package name from ahead of class names\n"
+ + " -excludedocfilessubdir <name1:name2:...>\n"
+ + " Excludes 'doc-files' subdirectories
with a give name\n"
+ + " -noqualifier all|<packagename1:packagename2:...>\n"
+ + " Do never fully qualify given pacakge
names\n"
/* + " -nocomment Suppress the entire comment body
including the main description and all tags, only generate the declarations\n"
*/
/**
+ " -genhtml Generate HTML code instead of XML
code. This is the\n"
signature.asc
Description: This is a digitally signed message part
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Cp-tools-discuss] Documentation updates,
Mark Wielaard <=