🚀 go-pugleaf

IMHO, the Javadoc way of doing things is fine.  Between that (assuming, of course,
that the writer of the doc comment was sufficently clear) and the Bean interface,
I don't see how anyone could *not* be able to use the public features of a class.
My strongest objections to the JBuilder help system is that the Borland beans have
a different formatting convention from Sun's files (e.g. including properties and
methods from all parent classes), and little UI things like not returning to the
same place in a page when hitting the back button (I always bounce to the top,
meaning that I again have to find where I was).

The Javadoc files are not supposed to teach you how to program in Java.  They're
intended to show you how to use objects of that particular class.

One thing that you might want to think about, though, is to have the docs
generated from the source code in real time (i.e. when the user clicks on th doc
tab), the way you do it with the design tab.  If it is supposed to work this way,
I haven't figured out how to do it.  I've had to use the javadoc utility from the
command line.

Rich Wilkman wrote:

> LRS:
>
> First off, the docs could be better.  I agree completely here.
>
> Okay, I'll bite.  How would you have expected to see the use of a core
> Java class constructor described in the online help such that a person
> new to Java would understand it.
>
> The Sun docs show a constructor for the target type that uses the type
> in hand (i.e., Integer(String) ).
>
> Language definitions are terse, but readible.  If you can't read and
> understand that it means you have a constructor for an object named
> Integer that takes a String, how would you want to see it phrased?
> How would you want it indexed so you could find it (assuming that
> searching on Integer is out of the question)?
>
> There has to be some baseline level of understanding of the language.
> Where do you draw it?
>
> -Rich
>
> LRS wrote:
> >
> > >Scott Garrison wrote:
> > >>
> > >> how to convert string to integer??      integer to string easy enough.
> > >>
> > >> stupid question but Jbuilder Doc SUCKS!
> >
> > Rich Wilkman wrote in message <355B2003.8878370F@corp.borland.com>...
> > >Scott:
> > >
> > >You need to pick up a good basic Java reference like Java in a
> > >Nutshell -- this has nothing to do with JBuilder at all.
> >
> > Sorry Rich, but you missed part of the point. Scott didn't say that JBuilder
> > per se sucks, just its documentation.
> >
> > And in that I agree wholeheartedly. Apparently the people at Sun who are
> > responsible for such things wouldn't know reasonable documentation if it bit
> > them. Stripping out comments via JavaDoc and then calling that a Help file
> > is a joke.
> >
> > If I had an employee who seriously suggested that, well, let's just say that
> > he would have just greatly damaged his chances for advancement in the firm.
> >
> > Borland's (oh, well, as long as we're talking about stupid things, pardon
> > me, Inprise's) mistake was rushing the product to market and accepting the
> > JavaSoft nonsense mostly verbatim, and not doing a decent job of
> > documentation.
> >
> > Which is what Scott was complaining about.
>
> --
>
> =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
> Rich Wilkman
> Senior Quality Assurance Engineer
> Borland JBuilder Team
>
> If you see something that looks like an opinion up there,
> it's mine and mine alone.
>
> Mail sent to me from the newsgroups won't bounce but will
> be ignored.  If I have time, I'll respond, but you  have
> a better chance if you confine your posts to the newsgroups
> =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=