Community
Participate
Working Groups
I20050920 A new API to get the Javadoc for a Java element is needed. This API will extract the Javadoc from the IBuffer of the Java element (underlying compilation unit, or attached source for a class file).
Would this be fine? /** * Returns the Javadoc in HTML format if found, null otherwise. * * <p>If this element is from source, then the javadoc is * extracted from the corresponding source.</p> * <p>If this element is from a binary, the the javadoc is extracted from either the * attached source if present or the IClasspathAttribute#JAVADOC_LOCATION_ATTRIBUTE_NAME * attribute of the corresponding classpath entry if set. * * @return a string with the Javadoc in HTML format. * @since 3.2 */ String getJavadoc();
Created attachment 27701 [details] Proposed API
Extracting the Javadoc from bug IClasspathAttribute#JAVADOC_LOCATION_ATTRIBUTE_NAME is covered by bug 110173 and should be a separated API. I don't think the API for this bug (extracting the Javadoc from source) should convert it to HTML. Dani, can you please confirm this ?
I find two API redundant. The purpose of this API is to retrieve the javadoc of the corresponding IJavaElement. For a binary element, the javadoc should be retrieve from the javadoc attachement if no source is available. This should be done transparently for the user. Having two APIs would force the user to make two calls. From my perpective bug 110173 is an implementation details of this bug.
Dani, I would need details to know what you expect. Right now this API proposal matches what you have internally. Could it be interesting to have two API? one to return the javadoc as it is in the source and one to return it as HTML source.
>I find two API redundant. The purpose of this API is to retrieve the javadoc of >the corresponding IJavaElement. For a binary element, the javadoc should be >retrieve from the javadoc attachement if no source is available. This is the easy case ;-) The question is what do we do if both are present? - the attached Javadoc might be better (since eventually being processed by some doclet) than the result of extracting it from the source. - the attached Javadoc might only contain public Javadoc. Clients might want the Javadoc from source as is (as pointed out by Jerome) i.e. not yet converted to HTML while the Javadoc from the attached Javadoc will be an HTML fragment. However, there should be an option whether to convert the source Javadoc to HTML or not (see JavadocContentAccess for how we currently offer it to clients). Could you also provide a reader instead of a string as we do in JavadocContentAccess?
Adding Martin to the cc-list since he implemented JDT UI's Javadoc access.
I think there are 3 kind of functionalities: a.) Binary Java elements that have no source attachment, but have a Javadoc location, should make use of the Javadoc location as good as possible for a source attachment replacement. -> E.g. create a source stub with Javadoc comments, member header stubs and maybe disassebled code. I think this is bug 110173 and would not require any new API, just an updated SourceMapper. With this change, all our code that gets the Javadoc from a member with source will work without change. (We offer API for this, see JavadocContentAccess). b.) The code that extracts Javadoc comments from a member (JavadocContentAccess) could be taken over by jdt core. A cheaper way of doing it is just to have new API that returns the source ranges of the Javadoc comment. The luxury way would be to give back the comment in a structured way (similar to the DOM-AST). I would suggest to simply add new api that returns the source ranges. Having the source ranges, it should be possible for users to use the DOM AST. c.) Code that extracts Javadoc for a member from an HTML page. This is code we don't have yet, and would have to be done when implementing a.). What we have is code that constructs an URL for a member: JavaUI.getJavadocLocation(IJavaElement element, boolean resolveAnchor), that then can be used to open a browser on the documentation of this member. Important: the Javadoc locations attributes are currently only defined for libaries, not for source. Javadoc for source does mostly not exist, or is out-dated. JDT-UI currently lets you define a location _per project_ (not per source folder!), and this location is currently not shared in the classpath but only internal.
(In reply to comment #6) > This is the easy case ;-) The question is what do we do if both are present? Would be up to the user to decide which one he wants to use? > Clients might want the Javadoc from source as is (as pointed out by Jerome) i.e. > not yet converted to HTML while the Javadoc from the attached Javadoc will be an > HTML fragment. However, there should be an option whether to convert the source > Javadoc to HTML or not (see JavadocContentAccess for how we currently offer it > to clients). Then we should offer an API that returns a string either in HTML or plain text according to a flag. We would have one API to retrieve from source and one to retrieve the javadoc from attached doc. > Could you also provide a reader instead of a string as we do in > JavadocContentAccess? What would be the avantage to get a reader?
It seems to me that returning a a html string is a bit too much for an API in the Java model as it already deals with representation (e.g. decition to use a list for the taks, make the tags bold ect.) A string would be better but I think this might be already too much as extracting the tags also requires to know if a tag is the first on the line. /** * This @tag is just text. (This is an inline {@tag}, what you really should do) * @tag This is a real tag as it is first on the line. */ As said, I think best would be just to have a new API that returns the source ranges of the Javadoc comment and we should have a way to use the DOM AST on just that source to get tags and descriptions.
Having a source range only would make it up to the user to convert to HTML. That is fine for me. So this API would return the source range if the javadoc is retrieved from the source or attached source for binary element. It would return null if no source is attached for binary element. Ok for you?
would this be fine? /** * Returns the Javadoc range if this element is from source or if this element * is a binary element with an attached source, null otherwise. * * <p>If this element is from source, then the javadoc range is * extracted from the corresponding source.</p> * <p>If this element is from a binary, the the javadoc is extracted from the * attached source if present.</p> * * @return a source range corresponding to the javadoc source * @since 3.2 */ ISourceRange getJavadocRange();
(In reply to comment #12) > would this be fine? > > /** > * Returns the Javadoc range if this element is from source or if this element > * is a binary element with an attached source, null otherwise. > * > * <p>If this element is from source, then the javadoc range is > * extracted from the corresponding source.</p> > * <p>If this element is from a binary, the the javadoc is extracted from the > * attached source if present.</p> > * > * @return a source range corresponding to the javadoc source > * @since 3.2 > */ > ISourceRange getJavadocRange(); This looks good to me.
+1
looks good! I would add to @return: a source range corresponding to the javadoc source or <code>null</code> if no source is available or the element has no javadoc comment.
I'll start implementing this one.
Maybe we should put this new API only on IMember since it has no meaning otherwise.
(In reply to comment #17) > Maybe we should put this new API only on IMember since it has no meaning otherwise. agreed
We might also want to add: * @exception JavaModelException if this element does not exist or if an * exception occurs while accessing its corresponding resource. Since we access the buffer of the corresponding IMember, we can either add a throws clause or silently consume the exception. I am inclined to add a throws clause.
So to summarize, we end up with this API: /** * Returns the Javadoc range if this element is from source or if this element * is a binary element with an attached source, null otherwise. * * <p>If this element is from source, the javadoc range is * extracted from the corresponding source.</p> * <p>If this element is from a binary, the javadoc is extracted from the * attached source if present.</p> * * @exception JavaModelException if this element does not exist or if an * exception occurs while accessing its corresponding resource. * @return a source range corresponding to the javadoc source or <code>null</code> * if no source is available or the element has no javadoc comment. * @since 3.2 */ ISourceRange getJavadocRange() throws JavaModelException; defined on org.eclipse.jdt.core.IMember.
Update title accordingly. The API is ready to be released if it is ok with you.
Created attachment 28542 [details] API + implementation
Created attachment 28544 [details] Regression tests I will release the binary files separately.
Fixed and released in HEAD. Regression tests added in org.eclipse.jdt.core.tests.model.AttachSourceTests.test110172 and org.eclipse.jdt.core.tests.model.CompilationUnitTests.test110172.
Verified for 3.2 M3 using build I20051031-0010
Hello, I just discovered this awesome API-extension in the release plan for 3.2. Does this mean it is now basically possible to extract all information necessary to build a JavaDoc documentation from the JavaModel? Is something like this planned to replace the external dependency on javadoc? Hm. But how about the JavaDoc associated with an IPackageFragment? Java 1.5 has the JavaDoc in the package-info.java (see https://bugs.eclipse.org/bugs/show_bug.cgi?id=83804 for more information about package-info.java) Thanks, Christopher
No there are no plans to change the Javadoc wizard to not use the javadoc command. There's more involved than just extracting comments from files. But this might be better discussed in a new bug report.
I would like to elaborate on the possible bug in comment #26: (In reply to comment #17) > Maybe we should put this new API only on IMember since it has no meaning > otherwise. That's right with the notable exception that a PackageFragment also has a JavaDoc comment (in the package-info.java) which should be accessible using the same interface.
*** Bug 75980 has been marked as a duplicate of this bug. ***
