Function Comments Help

Name:	Function Comments
Version:	1.3
Last update:	2019-10-17 13:28:30

Introduction
What is a 'Function'?
The 'Current' Function
Function Comment Templates
The Simple Template
The Standard Template
Comment Version History
Other Possible Templates
Creating Comment Templates
Preferences and Shortcuts
System Administrator Notes
Known problems
License and Disclaimer

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.