How best to include a copyright in JavaDoc?

Question

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 &copy; 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

Answer 1

Your approach lets you choose which classes, interfaces and members are copyrighted, or apply different copyrights for different parts of the source code. But in many cases (such as the Java API), the entire published API gets the same copyright notice. So we put the notice in the footer of each page:
-bottom '<font size="-1">Submit
a bug or feature<br><br>Java is a trademark or registered trademark of Sun Microsystems,
Inc. in the US and other countries.<br>Copyright 1993-1999 Sun Microsystems, Inc.
901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' ^
http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#commandlineexample
-DOug