We have extended the javadoc API to support source position information.
The following have been added:

package com.sun.javadoc;

/**
 * This interface describes a source position: filename, line number, 
 * and column number.
 */
public interface SourcePosition {
    /** The source file. Returns null if no file information is 
     *  available. */
    java.io.File file();

    /** The line in the source file. The first line is numbered 1;
     *  0 means no line number information is available. */
    int line();

    /** The column in the source file. The first column is
     *  numbered 1; 0 means no column information is available.
     *  Columns count characters in the input stream; a tab
     *  advances the column number to the next 8-column tab stop.
     */
    int column();

    /** Convert the source position to the form "Filename:line". */
    String toString();
}

public interface DocErrorReporter {
    /**
     * Print an error message and increment error count.
     *
     * @param pos the position item where the error occurs
     * @param msg message to print
     */
    void printError(SourcePosition pos, String msg);

    /**
     * Print warning message and increment warning count.
     *
     * @param pos the position item where the warning occurs
     * @param msg message to print
     */
    void printWarning(SourcePosition pos, String msg);

    /**
     * Print a message.
     *
     * @param pos the position item where the message occurs
     * @param msg message to print
     */
    void printNotice(SourcePosition pos, String msg);
}

public interface Doc extends Comparable {
	...

    /**
     * Return the source position of the documented entity, or null if 
     * no position is available.
     */
    SourcePosition position();
}

public interface Tag {
	...

    /**
     * Return the source position of this tag.
     * @return the source position of this tag.
     */
    public SourcePosition position();
}
Issue:
We would like to decompose and recompose source files

Solution:
Javadoc should expose the position(line number should be sufficient in clean code) of Members in the MemberDoc Interface. 

Motivation:
This would allow a custom doclet to completely decompose
a source file, interpretate additional information
stored in tags and recreate an equivalent patched source file.

This would allow simple round trip engineering development
with (or without) case tools like Together J.

N/A

Looks like he wants something like getRawSourceCode() along with 
line numbers of source code.
 xxxxx@xxxxx  1998-11-24

The line numbers are reasonable, as he may want to output errors.
In fact, WE should be displaying line numbers on out error messages.

 xxxxx@xxxxx  2001-03-05

Exposing the file/line number gives doclets all they
need to know to copy the raw source code directly from the
source files (as long as the source files are not in jar
files).  Therefore, there will be nothing like getRawSourceCode()
added to the Doclet API.
 xxxxx@xxxxx  2001-03-07

Verifying the bug based on the correspondence with the developer,
-----------------------------------------------------------------
4192783 asks for extensions to the Doclet API (AKA Javaodc API)
to allow a programmer to get the source position for any 
class, member, name, etc.  (Since Javadoc is not designed primarily 
for recomposing source files, it is sufficient for it to 
supply only the position and not the actual raw source code).
This should work even if javadoc outputs no errors or warnings.


 xxxxx@xxxxx  2001-10-09

We would like our doc to have a section for each method that enumerated the
'calls to' other classes.

Consider this method in the class SourcePath in the package
com.sun.tools.doclets.


    public File getDirectory(String name) {
        for (int i = 0; i < sourcePath.length; i++) {
            File directoryNeeded = new File(sourcePath[i], name);
            if (directoryNeeded.isDirectory()) {
                return directoryNeeded;
            }
        }
        return null;
    }

We would like the Javadoc for this function to show that the 'File' class was
used in this method.  I want to write a doclet that parses the body of all
methods to determine what classes and methods were used.