Itcl files written for Tycho should follow a certain style in the headers.
This page discusses file headers, Itcl file bodies are discussed elsewhere.
The Itcl editor has a file template menu choice that will insert the Itcl template file.
Below is a sample header:
# A circular list data structure. # # @Author: Edward A. Lee # # @Version: %W% %G% # # @Copyright (c) 1995-%Q% The Regents of the University of California. # All rights reserved. # # Permission is hereby granted, without written agreement and without # license or royalty fees, to use, copy, modify, and distribute this # software and its documentation for any purpose, provided that the # above copyright notice and the following two paragraphs appear in all # copies of this software. # # IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY # FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES # ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF # THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. # # THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, # INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF # MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE # PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF # CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, # ENHANCEMENTS, OR MODIFICATIONS. # # PT_COPYRIGHT_VERSION_2 # COPYRIGHTENDKEY ##########################################################################
tydoc
documentation, but briefly, a doc tag is a keyword, such as
@Author
that is at the start of a comment. Doc tags are
case-insensitive, and my be pluralized. The trailing colon
":
" is optional, and it is not part of the doc tag. If
the trailing colon is present, the tydoc removes it from the comment.
@Author:
-
The primary Author(s) of the file. If you have more than one
author, use @Authors:
. With multiple authors, the
last two names should be separated by and
# @Authors: Author One, Author Two and Author ThreePlease try to follow the existing naming convention that people use for themselves, some people use a middle initial, some don't.
@Contributor:
-
(Optional) People who have contributed to this file. If there
are more than one contributor, you can pluralize this.
@Version:
-
The Version control information for this file. The version
control system can automatically update special characters at
file check in time, so that the file can contain the date and
version number. Currently, we are using SCCS at UC Berkeley.
If you use the string
# @Version: %W% %G%Then SCCS will convert this to the file name, version number and date:
# @Version: @(#)Tycho.tcl 1.37 6/14/96Note that there is a space between %W% %G%, not a tab.
@Copyright
- The Copyright for this file.
Usually @Copyright
is not followed by a colon.
The issue of copyrights is fairly tricky, if you are an
employee of UC Berkeley, you should include the copyright as
it is printed above. Note that the special symbol is expanded
at our site at UC Berkeley to be the current year. The Tycho style guide
contains more information about copyrights.