Hello.
I am wondering how best to include a copyright notice, standard legal boilerplate, etc. in JavaDocs.
I realize that many developers include the text directly in a JavaDoc comment (perhaps using a template in their IDE for generating that automatically), but that seems less than ideal to me. Having a long boilerplate takes up a lot of unnecessary space in source files; with several hundred or thousand source files, that can be a big waste. Also, if the notice needs to be changed or updated, than going back to find and edit every instance of the notice can be challenging, even with a global search and replace. What I would like is basically the equivalent of an "include" tag that will include a single copyright notice wherever it appears, but JavaDoc does not appear to have a suitable feature.
The initial approach I have taken is to define a custom taglet with this ability. I am also playing with a custom annotation for noting copyrighted code as an additional reference to the copyright notice. The basic structure I have so far looks like this, in org.sample.legal:
- Copyright.java (interface defining a few constants such as default copyright date, default owner, etc. as well as the full default copyright notice)
- CopyrightAnnotation.java (annotation type for marking code as copyrighted)
- CopyrightTaglet.java (taglet for adding "@copyright" tags in JavaDoc)
Here's what the top of CopyrightTaglet looks like, to give a better sense of what it can handle:
package org.sample.legal;
import com.sun.tools.doclets.Taglet;
import com.sun.javadoc.*;
import java.util.Map;
/**
* Represents the "@Copyright" tag. If empty, the default copyright notice
* will be displayed.
*
* <p>This tag can be used in any overview, package, class, or interface
* {@link com.sun.javadoc.Doc}. This is not an inline tag.</p>
*
* <p>The tag can display a default value, the default value modified with
* a different copyright date, or a completely custom value. To display the
* default value, use "@Copyright" alone.</p>
*
* <p>To specify a different date, enter the copyright years separated by
* dashes (-) or commas (,); optional spaces are allowed. For example, the
* following will be recognized as valid dates:</p>
* <ol>
* <li>"@Copyright 1999"</li>
* <li>"@Copyright 1999, 2000"</li>
* <li>"@Copyright 2001-2003</li>
* <li>"@Copyright 2001-3, 2005</li>
* </ol>
*
* <p>To display a completely custom value, simply enter whatever text is to be
* displayed after the "@Copyright" tag.</p>
*
* <p>The text is displayed in italics to remind the reader of its
* importance.</p>
*
* @Copyright
*/
@CopyrightAnnotation
public class CopyrightTaglet
implements Copyright, Taglet {
private static final String NAME = "Copyright";
private static final String HEADER = "Copyright:";
The "@Copyright" tag by itself produces output (based on the constants in the Copyright interface) like this:
Copyright:
Copyright © 2008 by Sample Organization. All rights reserved.
I have this all working fine, but my main question concerns whether this is a reasonable approach. Is there a better approach to this problem of making a single copy of the copyright text available everywhere? What other approaches are common?
Thanks for any advice.
Edited by: Richard.J.Barbalace on Jun 25, 2008 9:16 AM
Edited by: Richard.J.Barbalace on Jun 25, 2008 9:18 AM
Edited by: Richard.J.Barbalace on Jun 25, 2008 9:20 AM
Edited by: Richard.J.Barbalace on Jun 25, 2008 9:22 AM