Usage of CVS Keywords in JavaDocs
In my Java code I use the following tag in all my class level JavaDocs:
/**
* Some text describing what this class is for...bla bla bla...
* @author: mkopka - Marty Kopka - 20101010 - 17:45:23pm
* @version $Id: $
*/
public class Fubar { ... snip .. class definition follows in here
...and then when I commit the code into CVS the
$Id: $ tag gets converted into:
...
* @version $Id: Fubar.java,v 1.1 2010/10/10 17:50:44 mkopka Exp $
...
Which is all well and good and Ive encouraged all my teams to follow this style as it gets you some bonus information for free basically. You dont need to do anything except put in the initial "Id" tag and then dont touch it from that point on. I'll get updated every commit from that point on and you get the name of the user committing the file, the time and date that they did so and the version in CVS of the current file commit. All good information to have, especially given that you dont have to update it yourself.
So what am I going to complain about...well nothing actually. I was just going to point out that the string that's substituted into the "Id" tag is actually made of of a number of small parts comprising the larger string. Should you not want all that information (although why you wouldn't I dont know)...but if you dont you can just pick and choose the bits that are good for you. As an example the code below shows the equivalence of the "Id" tag but made up of sub-component like tags.
...
* @version $Revision: $ $Date: $ $Author: $ $State: $
...
Which will then give: ...
* @version $Revision: 1.1.1.1 $ $Date: 2010/10/10 17:50:44 $ $Author: mkopka $ $State: Exp $
...
There's also no reason why ...in theory... you couldn't use these various substitutions inside your code itself (although it would take until a CVS commit before you got any info in it first time around. But I can see a case where a version number for example may be usefully stored in a String and later displayed in the application. Or, seeing as how there is also the possibility to use other tags to substitute in a branch name (amongst other info) you could use that along with version info to provide info to the client. I.e.: something like this I can see as a a possibility:
...
String versionAndBranch = "Branch: $: $ Version: $Revision: $";
...
... snip ... and then at some later date we can use the String above for logging, debugging, display to the client etc.
...
System.out.println("We are using source code from: " + versionAndBranch);
...
Now as mentioned, the example above would be empty until you committed the file, but that's not a great problem as normally you would commit the code prior to a production deploy (so the issue would only be in your local development environment). For further info on this I found the following link: http://www.idevelopment.info/data/Programming/change_management/unix_cvs/PROGRAMMING_Using_CVS_Keywords_in_File_Headers.shtml
Listing of CVS Keywords
Besides the substitution tags that I listed above there are a number of others that are also available (11 in fact ... or perhaps 12 if you include CVSHeaders from the latest version ... but not all versions have CVSHeaders so be aware of this prior to using it as your version of CVS may not support it). The following listing gives a list of all of the different substitutions available (which I pilfered from an number of different sites and cobbled the info below together. See the end for a listing of http://'s that I used to compile this).
| Keyword | Explanation |
|---|---|
$Author: $ | The user responsible for a change. $Author: markd $ |
$Date: $ | Date and time of the change, in GMT. $Date: 1999/12/23 21:59:22 $ |
$Header: $ | A collection of information: full path to the RCS file, revision number, date/time of last change (GMT), author, state, and locker. (lockers are a rare occurance in CVS)$Header: /cvsweb/cvs-guide/keyword.html,v 1.3 1999/12/23 21:59:22 markd Exp $ |
$Id: $ | Like $Header: $, but without the path to the RCS file. $Id: keyword.html,v 1.3 1999/12/23 21:59:22 markd Exp $ |
$Log: $ | Inserts the cvs log message. This behaves differently than other tags in that it just inserts new information after the keyword. It doesn't replace the keyword or modify existing text. $Log: keyword.html,v $ Revision 1.2 1999/12/23 21:59:15 markd Revision 1.1 1999/12/23 21:58:35 markd Note: See the following link for an explanation of possible issues with the use of the $Log: $ tag. http://www.network-theory.co.uk/docs/cvsmanual/Logkeyword.html |
$Locker: $ | The user who has a lock on this revision (usually nobody) $Locker: markd $ |
$Name: $ | If a sticky tag is in effect, this is the name of that tag. Otherwise blank. $Name: guide_release_1 $ |
$RCSfile: $ | Name of the RCS file in the repository $RCSfile: keyword.html,v $ |
$Revision: $ | Revision number $Revision: 1.3 $ |
$Source: $ | Full path to the RCS ",v" file in the repository $Source: /cvsweb/cvs-guide/keyword.html,v $ |
$State: $ | State of this revision. $State: Exp $ |
$CVSHeader: $ | A standard header (similar to $Header: $, but with the CVS root stripped off). It contains the relative pathname of the RCS file to the CVS root, the revision number, the date (UTC), the author, the state, and the locker (if locked). Files will normally never be locked when you use CVS. Note: This keyword has only been recently introduced to CVS and may cause problems with existing installations if $CVSHeader: $ is already in the files for a different purpose. This keyword may be excluded using the KeywordExpand=eCVSHeader in the `CVSROOT/config' file. See Configuring Keyword Expansion for more details. |
