Function Comments Help
Name: | Function Comments |
Version: | 1.3 |
Last update: | 2019-10-17 13:28:30 |
The Function Comments package provides capability to insert nice comments for any given
function definition. Once this package has been turned on
a new Text ↣ Function Comments submenu includes different commands for
template insertion, allowing you to also create custom comment templates.
Click here to open the Features Preferences dialog and activate
this package.
Introduction
Informative annotation is one of the hallmarks of good programming.
Unless you are writing files strictly for your own personal use,
explaining how and why a particular set of code works makes it much
easier for colleagues present and future to decipher your code and update
it as necessary. (Even if you are writing files that only your eyes will
see, annotation can be very useful when you revisit the file years
later.) Sometimes, while writing the annotation for fresh eyes you can
discover coding errors or design flaws, or figure out how to accomplish
some task in a much easier way.
Unfortunately, annotation is often the least pleasurable activity for
programmers who usually have much more code to write. This package not
only helps make function annotation consistent but also (hopefully) makes
the documentation process easier to undertake.
What is a 'Function'?
This package relies on the notion of functions for programming files.
A function is generally just a block of code with a unique name that can
be invoked by a processor (or by other functions), and often accepts
required or optional arguments; the declaration syntax of a function is
often some variation of
"function type" "function name" "arguments" "function body"
Just as each programming language has different (and sometimes multiple)
types of functions, each Alpha mode has its own method for identifying
functions in the active window.
For Tcl files, for example, a function could be a proc or namespace
such as
proc testProcedure {argument1 {argument2 "1"} {argument3 ""} args} {
# This does something special
return "1"
}
while a Java function might be
public static void main(String[] args) {
Frame f = new AllComponents("AWT Demo");
// We should call f.pack() here. But its buggy.
f.resize(450, 475);
f.show();
}
and a Lisp function could be
(defun S-backward-to-start-of-continued-exp (lim)
(if (= (preceding-char) ?\))
(forward-sexp -1)
)
(beginning-of-line)
(if (<= (point) lim)
(goto-char (1+ lim)
)
)
(skip-chars-forward " \t")
)
Because the body of functions is usually indented, for many modes the
start of a function is indicated when some characters appear in the first
column of a line, and the function ends when all of the subsequent
opening delimiter characters are matched.
In general, in order for a function comment template to be successfully
inserted by the commands found in this package, the function must be
syntactically correct, including the proper matching of any delimiting
characters such as {}, [], ().
The 'Current' Function
For the purposes of this package (and this Help window), the current
function is the one which surrounds the cursor in the active window, or
(if the cursor is not in the body of a function) the first one found
immediately below the cursor.
When a Text ↣ Function Comments command is selected, it will operate on
the current function. If no function can be found, the operation takes
place in the line just above the current cursor position.
Function Comment Templates
This feature creates nicely formatted comment blocks above the current
function so that you can explain what it is supposed to do, which
arguments are required, what side effects might take place, who was
responsible for the original or any updates, etc.
Here's an example of a basic (standard) comment for a Tcl procedure:
##
# ------------------------------------------------------------------
#
# "function::updateCommentPref" --
#
# Called by the AlphaTcl SystemCode after the value of a preference
# for this package has changed, ensure that all other variables are
# updated properly and the menu is rebuilt if necessary.
#
# Author: Craig Barton Upright
# E-mail: cupright@alumni.princeton.edu
# www: https://www.purl.org/net/cbu/
#
# Argument Default In/Out Description
# ------------ -------- ------ -------------------------------------
# prefName In The preference name whose setting has
# been changed by some SystemCode proc.
#
# Results:
#
# None: no value is returned
#
# Side Effects:
#
# The "Function Comments" menu will be rebuilt.
#
# --Version--Author------------------Changes------------------------
# 1.0 cbu original
# 1.1 cbu ensure that the menu is properly rebuilt.
# ------------------------------------------------------------------
##
;proc function::updateCommentPref {prefName} {
# proc definition here...
}
The style of the template can be adjusted as described below. Each of
the fields (i.e. Author, Description, Results) is inserted as an
electric template; pressing your Next Stop keyboard shortcut will
move the cursor to the next field for you to type in the required data.
See the Electrics Help file for more information about such templates.
The Simple Template
The command Text ↣ Function Comments ↣ Simple Template will insert a
comment block which includes only the name of the function, as in
##
# ------------------------------------------------------------------
#
# "function::initializeComments" --
#
# •«description»
#
# ------------------------------------------------------------------
##
proc function::initializeComments {} {
global PREFS
...
}
The cursor will be inserted at the •description• template stop so that
you can fill in the details.
The Standard Template
The standard template can include much more information, such as
Author Name |
Author Email |
Author Web Site |
Arguments Table |
Results |
Side Effects |
as seen in the example found above in the Function Comment Templates
section. The Name/Email/Web Site data is obtained from the settings
for your Current Identity; see the package Identities help window for
more information.
Select the Text ↣ Function Comments ↣ Standard Template Options command
to adjust the fields that you want to include.
The comment version history field will only be added when you select
the command Text ↣ Function Comments ↣ Standard With Version Info.
If you choose to create your own custom template as described below, this
standard template will be provided as a model.
Comment Version History
When you select Text ↣ Function Comments ↣ Standard With Version Info,
the standard template is inserted and will include a table with version
history information as in
# --Version--Author------------------Changes------------------------
# 1.0 cbu original
When you update your function, you might want to add a note in this
history table explaining what has changed and why. Selecting the command
Text ↣ Function Comments ↣ Update Version Info will scan the
surrounding text and, if this history table can be found for the current
(or the next) function a new entry will be added.
If no history table can be found in the comment block for the current
function, a new one will be inserted. If no function comment block can
be found, you will be prompted to insert a new comment template.
Other Possible Templates
If the mode of the active window has defined its own set of function
comment templates, these will be included at the top of the menu.
If your system administrator has installed other function comment
templates, these will be included in the middle of the menu.
In either case, you should experiment to see what these commands do, and
consult the mode's documentation (or your sysadmin) for more information.
Creating Comment Templates
You might find that the default templates don't suit your needs, in which
case you can define your own custom templates.
Selecting Text ↣ Function Comments ↣ New Comment Template will prompt
you for the name of your new template, and then an editing window will
appear with more instructions. The current standard template will be
included as a model that you can adjust as you see fit.
When you have finished modifying your custom template, just save the
editing window and the new template will be available as a command in the
Text ↣ Function Comments menu.
Your custom templates can be edited, renamed, or removed later by
selecting the appropriate Text ↣ Function Comments command.
Your custom templates are saved as files in your Application Support
folder, and will still be available when you update your Alpha
application in the future. Click here to open the
Comment Template Folder.
Preferences and Shortcuts
The Text ↣ Function Comments ↣ Standard Template Options
command opens a dialog allowing you to adjust the various standard
template settings. Note that the Empty Line After Comment setting
applies to all comment templates inserted by this feature.
Menu shortcuts can be set for any Text ↣ Function Comments template
item using the standard Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Menu Shortcuts
command. Click here to open the Menu-Shortcuts Preferences panel.
System Administrator Notes
If you want to define additional default comment templates, all you need
to do is copy your custom template file from your user support folder
and then install it in the
$SUPPORT(local)/Templates/Comments/ folder.
They will be included in the middle of the Text ↣ Function Comments
menu for all users, although only you will be able to edit them. See the
Support Folders Help file for more information about changing Alpha's
behavior using Support Folders.
Known problems
Please report any problem or bug you encounter to
Alpha's Bug Tracker.
License and Disclaimer
Copyright (c) 1997-2019, Vince Darley and Contributors.
Contributors: Craig Barton Upright.
All rights reserved.
The Function Comments package is free software and distributed under
the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
- Neither the name of Vince Darley nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL VINCE DARLEY OR THE CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.