This has been fixed but is in an internal package.  It is not a supported API.
 xxxxx@xxxxx  2003-09-16The Taglet class is fine for simple tags, but has limitations.

- Extend the Taglet API to enable standalone tags to handline inline tags
  (both standard and custom) in their arguments.  This requires access
  to HtmlStandardWriter and Doc.  This is currently done
  by extending AbstractExecutableMemberTaglet

- Extend the Taglet API to enable access to HtmlStandardWriter.
  This is currently done by extending AbstractInlineTag

- Extend the Taglet API to enables multiple taglets to be 
  put in a single jar file (taglets.jar) and loaded with a single option.
  A suggestion for this can be found under Suggested Fix.




A major goal is that a third party developer should be able to reimplement a standard 
tag with *all* of its standard functionality, including supporting inline tags.
All of this should depend only on the new internal API (SPI) resulting from the refactoring
work.  That is, taglets should not break in the future if we later reimplement the
standard doclet.
======================================================================

N/A

Requires submitting a JSR
 xxxxx@xxxxx  2002-03-18

I think that designing the Taglet interface was a good idea but I think we
should have a special interface that is just for standard doclet taglets. 
Taglets that extend this interface should have access to the HtmlStandardWriter
and the Doc object that holds the tag.  We should put this API in its
own package.

 xxxxx@xxxxx  (by  xxxxx@xxxxx ) 2002-03-18




Also see 4654636 "Taglet does not allow use of inline tags"
 xxxxx@xxxxx  2002-06-29

We have been cleared by the Tiger planning committee to pursue
this feature.
 xxxxx@xxxxx  2002-08-09

Concerning the taglet jar feature,  xxxxx@xxxxx  wrote:
> The method mentioned in the "suggested fix" works for the user because he 
> knows the names of his tags and hard codes them in the register method.  
> It does not work for us because all we have is a JAR file.  We would have 
> to iterate through the classes in the JAR file and then register them one 
> by one.  That would be a useful feature for users who have a lot of 
> taglets and don't want to register them one by one.  To identify this 
> JAR file that only contains taglets, maybe we can give it a special name 
> like taglets.jar.  We can't just load classes from any JAR  file because 
> there is nothing stopping users from putting tools.jar in
> the taglet path.  We wouldn't want to iterate through that.

 xxxxx@xxxxx  replied:
I wouldn't want to restrict this to only one jar file.
Then people couldn't build libraries of taglets or
share them as easily.

Why would someone put tools.jar in taglet path? 
It's documented that -tagletpath is for taglets.
It seems reasonable to me to expect that a jar file
in -tagletpath should contain only taglets.

Or might someone create taglets that depend on
other non-taglet classes, and want to jar them all
up in a single jar file?  When you iterate through
the classes, you can tell which are taglets and which
are not, can't you?  If you can, this would also seem
reasonable to allow non-taglet classes.

jamie's reply:
>Why would someone put tools.jar in taglet path?

I don't think anyone would do this but I am just worried that the doclet will
run slowly because it will have to iterate through a large JAR.

> It seems reasonable to me to expect that a jar file
> in -tagletpath should contain only taglets.

If we can assume this, I guess there is nothing to worry about.

> Or might someone create taglets that depend on
> other non-taglet classes, and want to jar them all
> up in a single jar file?  When you iterate through
> the classes, you can tell which are taglets and which
> are not, can't you?

I can tell which classes are taglets in the JAR.  I guess that will be our
proposal then.  Iterate through all the classes and register that ones that
implement a Taglet interface (old or new).

 xxxxx@xxxxx  2003-07-19


First a comment about registering multiple taglets in one register call.
I've actually done something like this myself, but I noticed that it seems
to bypass a bit of sanity checking that the standard doclet does for you.
After each call to "register" the doclet looks at the single taglet most
recently registered, and does some processing on its name.  If several
taglets are registered at once, only the final one gets processed. 

It would be possible for the tagletMap implementation to be smarter and
handle this correctly.  While I'm on the subject, the tagletMap implementation
could also be smart enough not to require you to unregister an existing taglet
before registering a replacement.  

But forget all this talk about improving the register method.
I really like the idea of doing away with taglet registration altogether.

It seems entirely reasonable that Some Big Project with its own taglets
will come all packaged up in SomeBigProject.jar, which would then serve for both
the classpath and the tagletpath.  So there certainly would need to be
a way to locate the taglets within the classpath.

Enumerating all classes and looking for taglets may be fine.  If that's
not desired -- either due to efficiency or because you lose some flexibility
in choosing your taglets -- there's a solution to exactly this
problem used in lots of places in the JDK and elsewhere:  take a look
at sun.misc.Service.  You create a file in the jar's META-INF/services
directory that lists all the taglets in that jar.  (Note that although the
implementation is in a sun.* package, there's nothing Sun-private about 
the mechanism itself.)

 xxxxx@xxxxx  2003-07-19

Fixed but not a supported API.
 xxxxx@xxxxx  2003-09-16