Using inline tags inside standalone custom tags
Is it possible to use inline tags, either custom or standard, inside custom tags created with taglets?
I have been unsucessful in getting this to work. To make it simple I just used the sample ToDoTaglet and UnderlineTaglets provided in the taglet overview on the javadoc page. I tried to do:
@todo does {@underline this} work?
And in the documentation I got back, the todo tag worked (i.e added the heading and set the BG color to yellow) but "this" was not underlined. I also tried with the @link tag to use a standard tag instead of a cusom one. That didn't work either.
Is there a way to do this or did I just hit a know limitation with the new taglet feature.
Thanks,
-Chris
[730 byte] By [
efreq] at [2007-9-26 19:41:18]
Jamie Ho wrote:
Yes, this is definitely possible. The @todo tag is
not "smart enough" to handle inline tags, but I know a
way to develop a taglet that is smart enough to do
this.
Tell Chris to develop a tag that extends
com.sun.tools.doclets.standard.tags.SimpleTaglet .
This will allow inline tags to be used with his custom
tag.
To test this, please try:
@author The author is {@underline Jamie Ho}
If my name is underlined above, then extending
SimpleTaglet is the correct thing to do.
-Jamie
(by Doug Kramer, Javadoc team)
Please let us know what happens.
Sorry for the long delay in getting back to this issue. Is there documentation for this standard taglet somewhere so I know what I'm extending. Or maybe I'm missing something because I don't have a ton of java experience. I would like to just modify either the example UnderLine taglet or ToDo taglet to extend them from the StandardTaglet. If I get that working then I can do the same thing to the taglets I'm defining.
I tried doing both:
public class UnderlineTaglet extends SimpleTaglet { ... }
public class UnderlineTaglet extends SimpleTaglet implements Taglet { ... }
and I added an import for com.sun.tools.doclets.standard.tags.SimpleTaglet.
But I get an error when compiling:
> javac UnderlineTaglet.java
UnderlineTaglet.java:53: cannot resolve symbol
symbol : constructor SimpleTaglet ()
location: class com.sun.tools.doclets.standard.tags.SimpleTaglet
public class UnderlineTaglet extends SimpleTaglet {
^
1 error
--
I apologize in advance if I'm overlooking something simple or doing something basic incorrectly.
-Chris
efreq at 2007-7-3 12:37:11 >
Please make sure that SimpleTaglet is on your classpath.(Use the -classpath option) Let us know if that helps or not.-Doug KramerJavadoc team
Oops. Wrong instructions on our part. To process inline tags,
rather than extending SimpleTaglet, you must extend AbstractExecutableMemberTaglet:
public class ToDoTaglet extends AbstractExecutableMemberTaglet {
and must import:
import com.sun.tools.doclets.Taglet;
import com.sun.tools.doclets.standard.HtmlStandardWriter;
import com.sun.tools.doclets.standard.tags.AbstractExecutableMemberTaglet;
import com.sun.javadoc.*;
import java.util.Map;
Set these as static final:
private static final String NAME = "todo";
private static final String HEADER = "To Do:";
and then implement String toString(Tag, Doc, HtmlStandardWriter):
/**
* Given an array of Tags representing this custom
* tag, return its string representation, with inline tags resolved. If
* there is no output, return null.
* @param tags the array of Tags representing of this custom tag.
* @param doc the Doc that we are generating documentation for.
* @param html The HTMLStandardWriter that will output this tag.
*/
public String toString(Doc doc, HtmlStandardWriter html) {
Tag[] tags = doc.tags(NAME);
if (tags.length == 0) {
return null;
}
String result = "";
for (int i = 0; i < tags.length; i++) {
result += toString(tags[ i ], doc, html);
}
return result;
}
The above changes are all you need. We have updated ToDoTaglet.java to support these tags,
which we will publish sometime Monday March 18 at:
http://java.sun.com/j2se/1.4/docs/tooldocs/javadoc/taglet/overview.html
regards,
-Doug Kramer
Javadoc team
On further investigation, the suggestion below only works for
tags in methods and constructors comments (executable members).
It does not interpret inline tags in fields, classes, interfaces
and packages comments.
We'll see if we can get a fix into 1.4.1.
-Doug
A nice solution I tried is the following:
private static Map taglets;
public static void register(Map tagletMap) {
taglets = tagletMap;
//...
}
String toString(...){
int j;
Tag[] nested=tag.inlineTags();
for(j=0; j<nested.length; ++j){
if(nested[j].kind().equals("Text")){
result += nested[j].text();
}else{
// don't know why this isn't working for @see / @link
Taglet taglet = (Taglet)taglets
.get(nested[j].kind().substring(1));
if(taglet==null){
result += "**taglet not found!!**";
}else{
result += taglet.toString(nested[j]);
}
//...
}
Unfortunately this is not working with @link tags as I hoped, therefore I had to hack a solution to print a html link.
Did I miss something ?
Marco.>
MTO at 2007-7-3 12:37:11 >
