4 Replies Latest reply on Sep 16, 2010 7:56 AM by 843810

    Adding an exclude tag to the Standard doclet


      I have looked over the javadoc documentation quite a bit and realized that there is no easy way to exclude classes and methods with a custom tag such as @exclude, but still use the standard doclet without modifying the doclets source. I have started to do this by making a copy of the Standard doclet classes and modifying them. What I was wondering is what would be the best way to accomplish what I am looking to do? Can I at the beginning of the doclet do an search through all classes and their methods and remove their names from the ClassDoc and MethodDocs? Or do I have to find every place in the individual writers and before writing the class or method out, check for my tag.

      I have seen the line

      Tag[] tags = methods[j].tags(tagName);

      Which seems like it could be useful.

      Could you point me to the files that I would need to modify to make the exclude tag work the easiest? I am not looking for speed, so an easy solution that adds a few milliseconds to the run time would work for me.

        • 1. Re: Adding an exclude tag to the Standard doclet

          Perhaps, my advice is a bit different than you are asking for... But there is a tool that would allow you to do all that stuff you need possibly in a five minutes.

          The tool is called DocFlex/Javadoc:

          It is a template-driven doclet (together with the graphic template designer to it). This is actually a very powerful tool. To exclude any classes or methods or fields by @exclude tag all you need to do is to specify the following filter:
          ! hasTag("@exclude")
          at a few places (called Element Iterators) within provided basic templates.

          Of course, such a filter could program any other condition you want. Just download DocFlex/Javadoc and see for yourself. If you are interested, we could also draw a five-minute-long viewlet explaining how to program your task. Just let us know by sending your request to our contact e-mail.

          In addition to this, DocFlex/Javadoc would give you lots of other benefits and unprecedented possibilities:

          (*) The basic set of templates provided with this tool is actually an equivalent of those Standard Doclet Java sources you're trying to modify now. That means, any stuff that gets into the generated documentation is programmed entirely within those templates.

          (*) The difference from the Standard Doclet Java sources is that those templates are somewhat 10 (or even more) times smaller and represented in the visual way. That is, you would mostly edit them in terms of the things appearing in the documentation rather than as Java operators.

          (*) The templates are absolutely open to everyone and are going to be such all the time. That is because the templates themselves are not our core product, rather they are the result produced with it.

          (*) You will get an output format independent Javadoc generator. Currently, the same set of templates can generate both high quality HTML and RTF. More major output formats will be supported later.

          (*) About in a month (or so), we are going to release version 1.5 with full Java 5 language features support.

          (*) There is a freeware edition of this tool called DocFlex/Doclet which both provides a ready to use doclet for generation of best quality RTF Javadocs and can be used as a free "player" for your custom templates.


          Leonid Rudy
          • 2. Re: Adding an exclude tag to the Standard doclet
            There is a specialized exclude doclet, working on top of the standard one:
            I just tried it, and it works, NP.
            • 3. Re: Adding an exclude tag to the Standard doclet

              We have done this now!

              Since DocFlex/Javadoc version 1.3, a new parameter in basic templates has been supported (in very those few places, as I said).

              The parameter is called "Exclude By Tags". It appears both in the parameter inspector dialog invoked from the Docflex/Doclet dialog, or can be specified on command line.

              Using this parameter, you can specify one or several tags, custom or not (e.g. that very '@exclude' tag if you wish) by which any classes, fields or methods contained one of those tags will be excluded from the generated documentation.

              Now, you can use this feature for free in DocFlex/Doclet -- freeware edition of DocFlex/Javadoc.

              Parameters in DocFlex templates serves the same role as ordinary command line options in ordinary doclet. Since all output generation is programmed within templates, the template parameters can control it in any way you wish.

              Leonid Rudy
              • 4. Re: Adding an exclude tag to the Standard doclet
                Have a look at https://developer.berlios.de/projects/padoclet/ . PublishedApiDoclet acts as a filter between the javadoc program and any normal doclet. It also contains a doclet to check the (filtered) javadoc for dangling references.

                PublishedApiDoclet works for Java 5 and 6 (publishedApiDoclet1.5-0.4.jar) and Java 2 (publishedApiDoclet1.4-0.3.jar). It is available on http://developer.berlios.de/projects/padoclet/. The downloadable jar-files contain the doclet, the documentation and the sources.