[ Pobierz całość w formacie PDF ]
.Taking X arguments…”, use, “Constructor taking X arguments, …”.Describing parameters is helpful in Java, because there is no syntactic means of ascribing the C++ concept of ascribing state constancy to a parameter; this even though some parameters might never be modified when used by the method.The description of exceptions also is excellent practice because they will either have to be caught by your client's code, caught and re-thrown, or passed on.Listing 37.2 illustrates a helpful method comment.lListing 37.2.Example method comment.l//=================================================================================/** * This method determines if the Finite State Machine is in one of the 2 * (desirable) states given.The StringBuffer parameter is the only one of the 3 * that may change during the execution of this call.Note that this method may * become private, so it may be a good idea to avoid it ! <br> * Has not been modified for some considerable time so could be considered stable * (or obsolete).<br> @param rStateOne An instance of FsmState.The order is * irrelevant @param rStateTwo An instance of FsmState.The order is irrelevant * @param rStrBuffer <b>volatile</b> This wil be updated during this call with the * state actually encountered if this function returns true * @return true if one of the two states has been encountered ; false (!) otherwise * @exception java.io.IOException Thrown when the Fsm delegator attempts to fetch a * token and fails.Unusual * @exception org.exceptions.FsmDead Thrown when the Finite State Machine is in a * GC'ablestate.*///=================================================================================protected boolean duplexState(FsmState rStateOne, FsmState rStateTwo, StringBuffer ÂrStrBuffer) { if (bTerminated) throw new org.exceptions.FsmDead(“FSM: Dead state entered”);Again, note the inclusion of <br> tags to introduce blank lines and the use of a boldface “volatile” comment on the rStrBuffer description to indicate its potential value change.Variable Comment ExampleBecause only the comments of protected and public variables are candidates for documentation inclusion, you might not see many of these.They seem to appear mainly for FINAL variables, which are really just a Java method for introducing constant values.Remember that variable comments for javadoc can only contain @see directives.Listing 37.3 shows a sample variable comment.lListing 37.3.Sample variable comment.l//=================================================================================/** * This boolean variable holds our live/dead status.It is held to be true through * out the useful life of the Finite State Machine, being rendered false only when * the associated token stream is in error or throws an exception.* @see org.io.streams.StackedTokenStream*///=================================================================================protected boolean bTerminated;Generating DocumentationNow we cut to the chase.We will discuss how to generate your documentation, where it can reside, platform differences, and errors that can occur.lWhere do documents go on creation?llgo wherever you happen to be, actually.What this means is best explained with an example.If you are in directory X, and you generate documentation for your package org.utilities, javadoc will dump its output in directory X.This is not particularly unfriendly unless you have manually edited Packages.html—if you have, the javadoc process will overwrite your changes! The moral of this example is that javadoc is essentially a batch utility if you don't want to change directories too often.There also is a command-line option you can supply to alter this behavior.llMerging your own packages with the Java API documentationllis entirely possible though not necessarily advisable.All you really have to do is edit the Packages.html file and insert your own hypertext links to your package documents.Note that merging your own documents this way will not include them in either the index or class hierarchy.llPlatform differenceslldepends very much upon your own system setup.For example, suppose you are using Windows NT javadoc to generate documents and these documents are targeted to be stored on a network drive whose native type is UNIX.This will generate documents that can be accessed under NT but not under a UNIX-based browser.Why is this? Case sensitivity.Generating from NT, javadoc seems to ignore case and the result is hypertext-linked documents that show up as errors under UNIX.This is a minor point, but if you are batch-creating documentation for a large package or number of packages, it might save you some time.In this sort of environment, maybe you should just go with UNIX-based generation!llOther errorsllout for the command-line syntax.You must specify a full package name, and the source must be available and readable.Any other course of action equals frustration.Make sure that you can write in the directory you are currently in or are directing the javadoc HTML documents to.ljavadoc: Command-Line Usagejavadoc is just about the simplest utility in the JDK.The syntax is as follows:javaDoc [options] {Package Name or File Name}.Available options are as follows:-d <directory>This instructs javadoc to redirect output to <directory>.The default is the current directory.-classpathThis allows the specification of a classpath.It is the same as javac and overrides the CLASSPATH environment variable.-verboseThis instructs javadoc to print a list of files loaded during execution.From JDK Beta 2, this might include files loaded from a ZIP file.Measuring Your Documentation Qualityjavadoc certainly is a tremendous help when it comes to automating the sometimes arduous task of creating software documentation.One aspect it does not cover is that of quality.This section attempts to provide some heuristics that can be applied to determine if the documents you are producing are worthy of a readership.Please note that a subset of this information also is included in the book Object Oriented Software Metrics by Mark Lorenz and Jeff Kidd, which is a recommended read for those interested in object-oriented metrics.The list that follows presents metrics that you might consider adopting:lSize/existence of class commentllthe object was important enough to warrant a class, it certainly has a purpose, provides some service, collaborates with others, or acts autonomously.Otherwise you probably would not have bothered, so it therefore deserves a comment—and not just one that mentions the date and version, either! As an API reader, you should be able to read the overall class comment and either discard the class from consideration or investigate further.Without a class comment of some depth, such a task is rendered more difficult.At least 50 words would be required for a small class, such as a support class
[ Pobierz całość w formacie PDF ]