Useful Generic Function Documentation

Guidelines for Useful Generic Function Documentation

To be really useful, generic function documentation should contain the following items.

1. Function Name in large type
2. A declaration if it is generic to all of ExtendScript, to all of JavaScript, unique to Adobe InCopy or Adobe InDesign.
3. The function's purpose. List what the function does and why you would want to use it. This should be like a sales statement -- why should a user want to use this function.
4. What is returned and under what conditions. Note, not every function has to return things. Some really useful generic functions modify things without returning anything.
5. What other functions are called. A perfect generic function shouldn't call other functions, but, sometimes it is handy, so list what other functions will be called.
6. Function Version or Edit Date. Because functions can be updated, it is a good idea to list the date the function was written or edited each time the function has changed.
7. Copyright or usage notes.

And example of a function which such documentation standards is the Has Notes function posted recently. That function only has about 6 real lines of code but because of good documentation standards, the function is much longer. But it makes the function usable to more people because they know how and why to use it.

Comments?