Re: input stream 101

In article <1123239300.949424.234500@xxxxxxxxxxxxxxxxxxxxxxxxxxxx>,
hawat.thufir@xxxxxxxxx <hawat.thufir@xxxxxxxxx> wrote:
>blmblm@xxxxxxxxxxxxx wrote:

[ snip ]

>> Wow. To me the benefit (automatically generating documentation that
>> looks like the "standard" documentation) justifies a certain amount
>> of ugliness in the source -- and anyway aside from the use of the
>> javadoc tags (e.g., "@param"), I don't find that my comments look
>> much different from the way they did before I discovered javadoc.
>> May be a "YMMV" thing, though.
>
>I've also never used it, yet. It looks like it's just like "javac" so
>I'll probably add it to my build file. It sounded perhaps more
>intimidating that it really is, to me.

I think that's the case (that it sounds more intimidating than it is).
"javadoc <list of source files>" is all you need to get *some* result.
Note that this puts the results in the current directory, so it can
be helpful to make a "docs" directory and cd there before running the
command. There is probably a javadoc option to fix that ....

>> I think there's also a school of thought that claims that if you
>> choose your method and variable names really carefully, you won't need
>> comments -- e.g., if you're writing a Circle class, does getArea()
>> really need a comment to explain what it does? I don't think this
>> always works, but sometimes it does.
>
>I think that breaks down once you move away from circles and into
>widgets. If you have a bit of high school geometry then it's
>accessible. I *imagine* that there are going to be times that heavy
>documention is required. For instance, a medical application. Unless
>you're a doctor it might be "greek" to follow that naming convention.
>It'd probably be Latin, actually.
>
>But, yeah, I at least subscribe to the school of thought that the name
>of a method/primitive/class/etc is very important. Not that I always
>follow it ;)

"Test16". :-)

About documentation, I like to think in terms of separating the
"what" from the "how". Documentation intended for users of your
programs or classes or functions should focus on the "what" (getArea()
returns the area of the circle, or rectangle, or whatever), while
documentation intended for people who might have to modify your code
can also discuss the "how" (pi * radius squared, or width * length).
With Java, I usually try to put only the "what" comments in a form
that will be processed by javadoc, with the "how" comments internal
to the class or method or whatever.

[ snip ]

>I'm thinking about how to approach mass-tidy-izing. Performance isn't
>an issue, so simply iterating file[n].html, for n=1 to 99, might be my
>next step. To make it a bit more practical, I'm going to have have to
>research how to do a "ls" (linux) or "dir" (windows) command to read in
>the contents of a directory. Once I have the contents of a directory,
>perhaps in an array or List, then it should be fairly easy to iterate
>through.

list() in the File class may help you there. Some simple example code:

String[] files = new File("/tmp").list();
for (int i = 0; i < files.length; ++i)
System.out.println(files[i]);

(If you haven't figured this out already -- the standard library in
Java has stuff that will help you with almost anything you'd want to
do. The problem is finding it.)

[ snip ]

>> And if the intended purpose of this code is to mass-convert 100+
>> files, my guess is that you'd be better served by something you can
>> run from the command line, because then .... Well, I'm thinking
>> in Unix/Linux terms, where the obvious way to do this would be with
>> shell-script constructs to loop over all the files, etc. I seem to
>> remember messages from you to a Linux mailing list? so maybe that
>> approach would work for you.
>
>Heh, which list?

fedora-list@xxxxxxxxxx

>Yeah, but this primarily about learning Java and only secondarily about
>this particular project. Really, I could've just typed some stuff into
>a spread*** :)

Not nearly as much fun. :-)

[ snip ]

>thanks,

You're welcome!

--
| B. L. Massingill
| ObDisclaimer: I don't speak for my employers; they return the favor.
.