United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4192783 : expose file/line/column of declarations.

Details
Type:
Enhancement
Submit Date:
1998-11-25
Status:
Closed
Updated Date:
2002-06-27
Project Name:
JDK
Resolved Date:
2001-06-22
Component:
tools
OS:
solaris_2.5
Sub-Component:
javadoc(tool)
CPU:
sparc
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.2.0
Fixed Versions:
1.4.0 (beta2)

Related Reports
Relates:

Sub Tasks

Description
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.


                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
merlin-beta2

FIXED IN:
merlin-beta2

INTEGRATED IN:
merlin-beta2

VERIFIED IN:
merlin-beta3


                                     
2004-06-14
PUBLIC COMMENTS

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();
}

                                     
2004-06-10
EVALUATION

Looks like he wants something like getRawSourceCode() along with 
line numbers of source code.
doug.kramer@Eng 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.

neal.gafter@Eng 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.
doug.kramer@Eng 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.


###@###.### 2001-10-09
                                     
2001-10-09



Hardware and Software, Engineered to Work Together