Extending standard doclet by subclassing: impossible?
Hi,
I'd like to extend the standard html doclet so that a class diagram appears just below the class name in every doc file.
I want to do that for an open source project, so I have to do it in a way that allows the redistribution of the doclet.
As far as I understand the licence, I can do that only by subclassing (because using the standard doclet source would prevent redistribution, right?).
Problem is, the standard doclet in 1.5.0 has been designed so that it's almost impossible to extend by subclassing, because many classes have private constructors.
I just need to add a link after the html generated by ClassBuilder.buildClassHeader(), but I cannot subclass HTMLDoclet because I would incur in the check AbstractDoclet.isValidDoclet(), and there's no way to change the HTMLDoclet configuration neither.
In the FAQ (http://java.sun.com/j2se/javadoc/faq/index.html#sourcedoclet) you suggest that the preferred way to extend the standard doclet is by subclassing, but in my opinion you made every step to make it impossible in practice.
Is there any way to achieve my goal, besides rewriting the whole doclet? (which would be not practical, it's an open source project and I'm working in my spare time).
Hi,
In the FAQ you suggest that the preferred way to extend the standard doclet is by subclassing, but in my opinion you made every step to make it impossible in practice.
Well, you are right. They just do what they would be supposed to...
Actually, nothing is for free out there. Someone has eventually to pay for everything...
The serious open source is in fact little more than yet another marketing trick. Just read some articles from "The Economist" magazine for that matter. Companies create open source for the following basic reasons:
(*) To earn from the paid services they offer around their open-source software;
(*) To compete with big guys like Microsoft (including creating the environment for that rivalry -- Eclipse and Apache are just about that)
(*) To promote a very new technology (educate the market first)
(*) To promote the non-open-source part of the whole software
So, I believe, most likely you will need eventually to write your own doclet from scratch... A big work!
Also, I suggest you to look at this product:
http://www.filigris.com/products/docflex_javadoc/
This is also a doclet and very much professional one. It is not an open source project. However, it is based on a very different technology that makes it somewhat an open-source.
If you have an idea of adding some diagrams to the generates Java API documentation, your idea might be easily integrated with our product... Just let us know if you wish any further discussion.
Everything best,
Leonid Rudy
http://www.docflex.com
I don't share your vision of open source, I've always worked on open source projects in my free time, or patched existing ones during my work time (and of course, contributed the patches back to the os projects).
Anyway, I work on UmlGraph (http://www.spinellis.gr/sw/umlgraph/), and I'd like to have something like the documentation generated by doxygen, and I want it for my open source projects again (especially for geotools, www.geotools.org).
I simply cannot add to the build a commercial tool, because everyone working on the project would have to purchase a license. If I had to achieve the same result on a commercial project, I'd simply buy yDoc: http://www.yworks.com/en/products_ydoc.htm.
But anyway, thank you for your offer :-)
> I don't share your vision of open source
I would love to share your vision too. But the economics reality defies it! All we could do about that is just to understand the truth and to adapt to it (like engineers understand the physics and make the aircraft fly -- the thing seemingly to be impossible).
If you really want to implement your new ideas, you won't be able to do it in your spare time... you will need huge a lot of resources for doing that. But who will pay you? A guy with money would never give you a cent without looking at his own benefits... Be sure!
> I'd simply buy yDoc
I know those guys quite enough... and that's exactly an example of a very much closed up company. We, on the contrary to them, are just looking forward for any integrations with the outside world !
> But anyway, thank you for your offer :-)
Well. If you are able to program the generation of the diagrams like yDoc does, DocFlex/Javadoc will be free for you! We just don't have time to do that ourselves. We could provide you a partner license. There's an DocFlex Open API (not published yet, but it's coming just soon). You can create you integration that generates those diagrams and insert them into the generated docs using your templates (all you would need is just to adapt the existing ones!), and then use/redistribute the whole thing together with the freeware DocFlex/Doclet engine as you like, in the open-source form or not. Everything you would have developed by yourself is yours!
Regards,
Leonid Rudy
http://www.docflex.com
> > But anyway, thank you for your offer :-)
>
> Well. If you are able to program the generation of
> the diagrams like yDoc does, DocFlex/Javadoc will be
> free for you!
No, we can't provide the same quality level. The quality
level is at the moment limited by the layout algorithms provided
by Graphviz, an open source layouter. You can see some samples
at:
http://www.spinellis.gr/sw/umlgraph/doc/ceg-view-packages.html
Implementing a true orthogonal layouter is a hell of a job, and
as you said, it cannot be done on spare time. But I'm content enough
with these limited results, they are better than not having a diagram at all anyway :-)
Hi,
I've looked at your page. The diagrams look nice!
Interestingly, do you generate them entirely automatically, or design partially by hands?
Anyway, I believe, we could do the integration!
The result tool may be similar to yDoc. The diagram elements will be hyperlinked to the corresponding docs. In addition, that tool will be able to generate an RTF documentation, which yDoc cannot. (In not so distant future, the PDF generation will also be added.)
The whole generate docs with your diagrams included may look something like that produced with another our product called DocFlex/Together. Please see, for instance:
http://www.filigris.com/products/docflex_together/examples/
The result tool may consists of the following things:
(1) our freeware DocFlex/Doclet engine
(2) your binaries to generate the diagrams
(3) the basic DocFlex/Javadoc templates adapted to include your diagrams
If the whole thing will be a freeware, that would be just great!
We would love it to exist ;=)
So, what's needed to make everything real is (1) your desire to do that and (2) the Open DocFlex API from us.
The Open API must be ready somewhere during the May (2006), I hope. As soon as it's ready, I will place an announcement here.
Meanwhile, if any questions, you may freely contact us directly by the e-mail (which you can find at our web-site).
Best regards,
Leonid Rudy
http://www.docflex.com
