©1996-2017 Roedy Green of Canadian Mind Products
This essay does not describe an existing computer program, just one that should exist. This essay is about a suggested student project in
Java programming. This essay gives a rough overview of how it might work. I have no source, object, specifications, file layouts or anything
else useful to implementing this project. Everything I have prepared to help you is right here.
This project outline is not like the artificial, tidy little problems you are spoon-fed in school, when all the facts you need are included, nothing extraneous is mentioned, the answer is
fully specified, along with hints to nudge you toward a single expected canonical solution. This project is much more like the real world of messy problems where it is up to you to fully the
define the end point, or a series of ever more difficult versions of this project and research the information yourself to solve them.
Everything I have to say to help you with this project is written below. I am not prepared to help you implement it; or give you any additional materials. I have too many
other projects of my own.
Though I am a programmer by profession, I don’t do people’s homework for them. That just robs them of an education.
You have my full permission to implement this project in any way you please and to keep all the profits from your endeavour.
Please do not email me about this project without reading the disclaimer above.
iDoc does a reasonable job of proofreading Javadoc, but
maintaining Javadoc is very tedious. Here are some tools you might write.
- A propagator. You write Javadoc for an interface, then you want to propagate it to
the classes that implement that interface. Ideally it could be interactive, making it
possible to replace, keep, or merge. In Java version 1.2
there are tools to make this easier.
- Parameter Boilerplate. If parameters are uniquely named, every place you see the
parameter formType in any method, there is canned boilerplate that
goes with it, plus perhaps a sentence of something custom for that particular method.
You want a way of being able to globally apply such boilerplate and to
update such boilerplate. Ditto for boiler plate explaining
- Javadoc needs tidying. To be maximally readable, the parameters must be in the same
order as in the method. There should be a blank line between each @param. Exceptions
should be listed in alphabetical order both on the method header and in the Javadoc.
The parameters and text should line up in columns as if the text had been placed in an
HTML (Hypertext Markup Language) header.
- Javadoc gets turned into HTML. The code should be verified as valid
just simply tag pair matching. I’m not user if characters like < are allowed
or if you must spell them out as <.
- A parser such as JavaCC or ANTLR (Another Tool for Language Recognition)
might be useful. See parser in the Java glossary.
- I often wish I could add electronic post-it notes to the Javadoc for the standard
Java classes. I could modify the HTML,
but then my notes would be lost the next time I updated the
JDK (Java Development Kit)
docs. I want a docLet that merges my comments as it generates the standard Javadoc
html. Ideally I should be able to take sets of notes from various friends and add
them and have their sources noted. They might each show up in different configurable
colours, e.g. by marking the comments with a style. The comments themselves would
look very much like skeletal Javadoced programs, with big hunks missing. I’d
hope once we had such a tool, people would write automatic generators for various
interesting information and would share their own lore. Perhaps the merge might work
on the HTML
created from Javadoc generated from the comments rather than trying to interfere in
generating process. What sets of comments might I like to see?
- a description of each class telling what it is for,
- piece of sample code for each class that uses the key methods.
- list of creators for the given class, methods outside
this class that return an object of this class.
- list of eaters for the given class, methods outside
this class that take one of these as a parm.
- Notes about similar classes and the differences between them.
- Where are the factory methods corresponding to private constructors?
- gotchas on methods.
- A navigator. You put all the Javadoc into an SQL (Standard Query Language)
database and then you can do queries to find things all methods that take a
Date and produce a long. It
could display all methods that produce an object of a given class (or a superclass).
It might be extended to find references to constants inside Java source method
bodies. You are no longer limited to statically created links.