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?

Generic ExtendScript Functions

What is a Generic ExtendScript Function?

A Generic ExtendScript Function is an ExtendScript (JavaScript for those that don't understand the difference) function that is not specific to a particular main script, but can be used in multiple scripts.

Generic ExtendScripts can be easily used in a 'Library' of script functions and called with

#include

Generic ExtendScripts can also be included in the body of scripts, and for most users, this is likely how they will be used.

A good Generic ExtendScript Function will have the following qualities:

• It is well documented. To be useful to others, they must be documented so that its use can be easily understood.
• It is self-sufficient. If additional functions are needed they are either included in the body, or are well documented in the function's header.
• Solves a unique problem and does it reliably.

This blog, ExtendScript Support, will be posting multiple Generic ExtendScript Functions and wants you to summit your functions for inclusion.