I just checked and JSDoc does exactly this. I.e. if the comment does not start with a tag, a "description" tag is assumed.
Well, that makes it less verbose then. All the tags are entirely optional, in fact. I would still like for at least a minimal (one liner) description to be provided for every function, and for arguments and return values to be documented wherever they are not obvious.
Can we agree on this, and on the use of JsDoc?
Also, Erick and I were also thinking that it might be good to subdivide our code into modules, instead of dumping everything into the global scope. We could do this by creating global objects and having functions as properties. These can then be documented using the @namespace tag inside JsDoc.
For example, I can modify memory.js as such:
/** @namespace */ memory = {
/** Adds a signed offset to a pointer value */ ptrAdd : function(ptr, offset) { }
/** Computes the difference between two pointers */ ptrSub : function(ptr1, ptr2) { } }
The functions can then be called by doing memory.ptrAdd, etc., and show up under the memory module in JsDoc. Note that this imposes a "one file per module definition" limitation, but I still think it's a fairly nice paradigm, as it allows our code to be better organized, and it implicitly allows us to check, say, that function foo is part of module bar, which could have special properties associated to it.
I also don't think it's a significant constraint on a naive optimizer. We can simply assume that functions inside global objects of the tachyon code never get redefined, and voilà (note that optionally, we could even explicitly make them read only properties if it's any kind of issue).
What do you think about that idea?
- Maxime