Javadoc convention suggestion

[Roedy Green]

If you encounter a package like JavaMail or JMF. there will be dozens
of classes. It would be very helpful if there were some sort of class
overview that said something like this;

to send an email, you will probably want to create objects in this
order class1, class2, class3....

to receive and email, you will ...

This gives you a handle on a logical order to approach studying the
classes.
--
Roedy Green Canadian Mind Products
http://mindprod.com

"The coolest thing to do with your data will be thought of by someone else."
~ Rufus Pollock (born: 1978 age: 31) in Talk.

 

[Knute Johnson]

If you encounter a package like JavaMail or JMF. there will be dozens
of classes. It would be very helpful if there were some sort of class
overview that said something like this;

to send an email, you will probably want to create objects in this
order class1, class2, class3....

to receive and email, you will ...

This gives you a handle on a logical order to approach studying the
classes.

Roedy:

That would be really handy for JavaMail. I've not seen a tutorial or
even a good article on how to use it yet.

 

[Lew]

If you encounter a package like JavaMail or JMF. there will be dozens
of classes.  It would be very helpful if there were some sort of class
overview that said something like this;

to send an email, you will probably want to create objects in this
order class1, class2, class3....

to receive and email, you will ...

This gives you a handle on a logical order to approach studying the
classes.

Are you suggesting something along the lines of
<http://java.sun.com/javase/6/docs/technotes/tools/solaris/
javadoc.html#overviewcomment>
or
<http://java.sun.com/javase/6/docs/technotes/tools/solaris/
javadoc.html#packagecomment>
?

 

[Martin Gregorie]

That would be really handy for JavaMail. I've not seen a tutorial or
even a good article on how to use it yet.

The JavaMail 'API Design Specification' is about the best (only)
programming guide I've found. It describes how the components fit
together and contains a number of useful source code examples.

However, just now I looked at the Javamail pages to confirm its name and
availability but couldn't find it. If you have no better luck, contact me
directly: I have a copy of the API design specification v1.4, which I
downloaded when I originally downloaded JavaMail and started to learn how
to use it.

=====
I agree with Roedy's general point: many of the more complex packages
need this type of documentation and quite a lot of Sun's tutorials could
do with expansion: in some cases you really have to know how to use a
class before the tutorial makes sense.

 

[Donkey Hottie]

If you encounter a package like JavaMail or JMF. there
will be dozens of classes. It would be very helpful if
there were some sort of class overview that said
something like this;

to send an email, you will probably want to create
objects in this order class1, class2, class3....

to receive and email, you will ...

This gives you a handle on a logical order to approach
studying the classes.

I will propably follow you in short order, as I have just decided to learn
JavaMail and Java Severe Faces and create a WebMail product without
OpenSource kits in it.

Well, except the Java, that is ;D

 

[Lew]

But there is already an overview for JavaMail at
<http://java.sun.com/products/javamail/javadocs/>
that includes one simple example, and links to
<http://java.sun.com/products/javamail/FAQ.html>
and
<http://java.sun.com/products/javamail/>

From the latter there are links to
<http://java.sun.com/products/javamail/reference/techart/index.html>
which in turn links to a couple of articles on how to use JavaMail.

If you keep following links from these places, you will encounter
<http://java.sun.com/developer/onlineTraining/JavaMail/index.html>
and
<http://java.sun.com/products/javamail/JavaMail-1.4.pdf>

I really do not see how much more of an overview one could hope for.

I will propably follow you in short order, as I have just decided to learn
JavaMail and Java Severe Faces

Good one!

Fortunately for you, Sun has long since granted Roedy's wish for an
overview of these technologies.

and create a WebMail product without OpenSource [sic] kits in it.

Well, except the Java, that is ;D

Why do you seek to avoid open source "kits"?

I am aware of two libraries for Java Server Faces (JSF), both of which
are open source, but not of any proprietary JSF implementations. Good
luck with that. You might just be stuck with having to use a free (as
in beer), open-source version. Poor you.

 

[Daniel Pitts]

If you encounter a package like JavaMail or JMF. there will be dozens
of classes. It would be very helpful if there were some sort of class
overview that said something like this;

to send an email, you will probably want to create objects in this
order class1, class2, class3....

to receive and email, you will ...

This gives you a handle on a logical order to approach studying the
classes.

This often goes in the "package.html", or some other external
(non-JavaDoc) documentation.

I call this Goal Oriented Documentation, AKA How-To.
Other terms I use:
"Exposé Documentation" everything this package offers
"Reference Documentation" JavaDocs are generally of this sort.
"Explanatory Documentation" explains systems and interactions (for
maintainers).
"Tutorial" explains what is possible with this system, from a basic level.

 

[Donkey Hottie]

Why do you seek to avoid open source "kits"?

I am aware of two libraries for Java Server Faces (JSF),
both of which are open source, but not of any proprietary
JSF implementations. Good luck with that. You might
just be stuck with having to use a free (as in beer),
open-source version. Poor you.

Well I'm in the the very beginning with this, but I can write a Faces
application without delivery of any implementation using the RI on
development environment but not attaching the libs in the product. Does not
work on Tomcat, but works with any Java EE 5 container.

Why not Open Source? I don't want to share my code.

 

[Arne Vajhøj]

Well I'm in the the very beginning with this, but I can write a Faces
application without delivery of any implementation using the RI on
development environment but not attaching the libs in the product. Does
not work on Tomcat, but works with any Java EE 5 container.

Why not Open Source? I don't want to share my code.

That does not exclude open source.

If your usage of the kit can be considered linking it may
exclude GPL.

But very few libraries are under GPL.

Arne

 

[Lew]

That does not exclude open source.

If your usage of the kit can be considered linking it may
exclude GPL.

But very few libraries are under GPL.

You can use Mojarra under the CDDL and MyFaces is under the Apache License.
<https://glassfish.dev.java.net/public/CDDL+GPL.html>
<http://www.apache.org/licenses/LICENSE-2.0>

Neither one precludes your use in proprietary code, nor do they preclude
making your software cost money.

It is silly to think "open source" means "I give up my rights to my code".
Quite the opposite. Dismiss that myth posthaste.

 

[Lew]

This often goes in the "package.html", or some other external
(non-JavaDoc) documentation.

And it also goes in Javadoc documentation, as in the case of JavaMail, for
example.

I call this Goal Oriented Documentation, AKA How-To.
Other terms I use:
"Exposé Documentation" everything this package offers
"Reference Documentation" JavaDocs are generally of this sort.
"Explanatory Documentation" explains systems and interactions (for
maintainers).
"Tutorial" explains what is possible with this system, from a basic level.

At least the last three of those are available for JavaMail, including
project- and package-level Javadocs.