stddoclet: @insert or @include reference material (source, overview)

Name: vi73552 Date: 02/23/99


>java -version
java version "1.1.7"
>java -version
java version "Linux_JDK_1.1.6_v1"


It would be nice if I could set up a in-line links to external documents that are COPIED
(in-lined) by javadoc into the final documentation tree. Javadoc would COPY the
specified document into the destination documentation hierarchy (assuming it will
at least display as valid HTML).

This could be used for inserting whole source files and specifications, shown here.
The advantage to source files is that the included file can be tested easily and
independently of when it is included in the text.

/**
 * For a simple example see
 * <PRE>{@include "MonitorFoo.java"}</PRE>.
 *
 * For a full spec, see {@include "monitor print spec.html"}.
 */

Or this feature could be used for inserting a snippet, if there is a convention
for starting and stopping the insertion within a file:

public class MyClass {

   private String field = "hi";

   // <BEGIN_SNIPPET>
   public String myMethod() {
       return field;
   }
   // <END_SNIPPET>
}

Better yet, the snippets could be named so that there could be several
to a file. Here's it's named "myMethod":

   // <BEGIN_SNIPPET: myMethod>
   public String myMethod() {
       return field;
   }
   // <END_SNIPPET>

Or use XML:

   // <Snippet name="myMethod">
   public String myMethod() {
       return field;
   }
   // </Snippet>

(Review ID: 48113)
======================================================================

Name: rlT66838 Date: 01/24/2000


C:\>^Cjava -version
java version "1.2.2"
HotSpot VM (1.0.1, mixed mode, build g)

Issue: in long javadoc comments with big code samples it's a hassle
to enter it and make sure the '*'s align nicely, and it's then
hard to read - I know that javasoft is not into massive comments, but
for us we find it desirable to make the javadoc cover as much
ground as possible.

So the idea is that instead of:

/**
 * Synopsis...
 *
 * Example:
 *
 * <code>
 * line 1..
 * ...
 * line 1243....
 * </code>
 */

One could enter:

/**
 * Synopsis...
 *
 * {@include example.html}
 */

And then example.html would be sucked in the javadoc from doc-files/
[or maybe not, as the semantics of doc-files is to copy
those things - ok, correction, the arg to @include would be relative to
the current dir so above it would have to be in the current dir].

JSP has an include tag which is useful for similar instances.
The arg to {@include} would be any file (*.html or *.txt) and would
just be inserted right there into the output stream [and let's say, not
otherwise processed for other javadoc tags].

(Review ID: 100278)
======================================================================