" $command_mode:/group "; " /GROUP NEW groupname member[,member,...] "; " /GROUP KILL groupname "; " /GROUP groupname ADD|DEL member[,member,...] "; " /GROUP [groupname[,groupname,...]] "; " ";It is important to remember that users will not be reading this content, developers will so use the description most comfortable for a developer.
" $command_mode:/verbname "; " /VERBNAME args "; " /VERBNAME other-args "; " "; " username mm/dd/yy - change description (PR#num) "; " ";
The parameter list has the form of a list of typenames (e.g. INT, STR, LIST, ERR, and FLOAT). If the typename is prefixed with a ? then it is an optional parameter. After the verb name line, the parameter's semantics are defined in detail (including the default value for a parameter).
The sendlist verb provides an excellent example of this:
" $lily_utils:sendlist(LIST, INT, INT, ?INT, ?INT) : LIST "; " args[1] The names of the objects to search for "; " args[2] Whether to look for multiple matches: 1 true, 0 false"; " args[3] Whether to search against unconnected objects: 1 true, 0 false "; " args[4] What domain to match against: 1 users, 2 discs, 0 either. "; " args[5] Extensions: 1 expand found groups, 2 joined discussions only "; " returns a list of object numbers matched "; " ";The format for verb comments is:
" $object:verbname(TYPE, TYPE) : TYPE"; " args[n] argument description "; " args[n] argument description "; " "; " username mm/dd/yy - change description "; " ";In the body of a verb there are two kinds of comments:
" this is a comment ";OR
" "; " this is a long... "; " multiline comment of some kind "; " ";The latter is not well supported, but it will be. -- CoKe - 01 Oct 2003 The comments were stripped back during the time when the RPI lily server was still running on my NeXTstation (aka eclipse.its.rpi.edu). Stripping the comments did improve performance enough that I was able to delay a memory upgrade to eclipse for six months. During those six months, the cost of that memory upgrade dropped by over $1,000 (iirc, the cost went from over $1,500 to under $300). I don't remember when the memory upgrade was, but I know we continued to run lily on eclipse for at least a year after the new memory was installed. And it looks like the day we stopped running lily on eclipse was Aug 22, 1998. My guess is that the comments were stripped sometime between 1995 and 1997. -- GaranceDrosehn - 16 Dec 2003 I'd also say that we might want to update these comment-related coding standards. Now that verbs are collecting a list of change-descriptions, that list can get rather long. It might be better to move those to a comment block at the end of the verb (with an explicit 'return;' command before them). That way, @how will just show the calling conventions for the verb, and we could have some other verb (like @history) to show the list of changes made. I'm not exactly sure on what format I'd like to see, or even if I'm heading in the wrong direction with these ideas, but the longer lists of change notices is making @how less useful... [btw, @how should be improved so you can optionally specify which object you want the verb from. We have several cases of the same verb on different key objects, and AFAIK @how can only display the info from one instance of that verb] -- GaranceDrosehn - 16 Dec 2003 So, I have been thinking of some alternate standards for coding info into comments. This is partially a reaction to the long list of change-notices that we have at the start of a verb -- now that we're trying hard to include comments for each change. I'm also thinking of how we might things to work if we ever do implement some kind of LilyInCvs scheme. FIrst, I would like @how to only show the calling conventions for a verb, and maybe a last-change time. I'd like to move a lot of other info into separate sections of comments. Since I want sectionS of comments, I also came up with the idea of having a non-comment delimiter to indicate the beginning and end of these sections. So, the comment header (for documenting the calling sequence) could look like:
" $object:verbname(TYPE, TYPE) : TYPE"; " args[n] argument description "; " args[n] argument description "; " "; " yyyy/mm/dd - developername "; " ";Just one line to say when it last changed. Then, the end of a verb could look like:
return; ______[changelog]; " -------+---------+---------+---------+---------+---------+---------*"; " "; " yyyy/mm/dd - developername "; " Description of most recent change ... perhaps spanning several lines "; " "; " yyyy/mm/dd - developername "; " Description of the previous change ... perhaps spanning several lines "; " "; " yyyy/mm/dd - developername "; " Description of even older change ... perhaps spanning several lines "; " "; ______[end]; ______[notes]; " Discussion of important issues for this verb, such as 'this verb should never "; " use the player variable, because it is not operating on the *current* player "; ______[end]; ______[todo]; " Talk about possible enhancements to this verb, or things that don't quite "; " work right yet. Perhaps it's dumb to have this section in the verb, and "; " all such ramblings should always be in the WiKi. For small things-to-fix "; " issues, I expect it would be more likely to be kept up-to-date if the "; " comments are in the verb where the work needs to be done. "; ______[end]; ______[snippets]; _Perhaps lines of code that is useful for debugging. Occasionally I find myself code which is very useful for debugging, but is just a waste of cycles in normal operation. Once I've solved the immediate problem, I kind of hate to completely delete that code, so it'd be nice to "save it away" somewhere useful._ ______[end];The statements like '______[blah];' seem to be accepted as valid commands by the command-parser, and all of these sections would be after a 'return' statement so they'd never be executed. Think of the initial one-line timestamp as the '$Id$' line that you'd have with CVS, and the change-log section as the '$Log$' section. The various '______[blah];' sections could be in any order, of course. I'm not sure how great all of that would work out, I just wanted to present some sample ideas. I'd kind of like to do the single-line timestamp in the header comments, and move all the change-descriptions to a [changelog] section at the end of verbs, if other developers think that is reasonable. The other parts are just rambling ideas, to show possible reasons for allowing for multiple sections. -- GaranceDrosehn - 30 Dec 2003