When I write scripts, it is not uncommon to forget how to use the script (usually handler scripts) or exactly what the script covers (usually regression scripts) a year or so later. I used to use comments to note the usage and underlying assumptions, but now I create a sub-handler a the end of the script so I don’t have to visit the actual script. This handler simply returns text describing whatever is important and relevant.
to help
return "This script does this and that. It requires passing the parameters a,b and c. D is optional. "
end help
// or multi-line example:
to description
return {{
This script does this and that.
It requires passing the parameters a,b and c. D is optional.
}}
end description
As you’re trying to remember how to use a script, you can use the “Do” line [eggPlantMatt: the Ad-Hoc Do Box, which is the text field at the bottom of the Run window] to get the text.
put myComplicatedScript.help
You can choose to use any name you want, but I have used “help”. Other options might be “description” , “usage” or whatever your team decides makes sense. You can also have separate ones for different purposes.
Another use is for including a description in the results of a test run. I have an email that pulls these from whatever regression scripts are executed. This way the people on the email list know what was covered in the testing session.
I hope this helps. I think your co-eggplanters will appreciate it.