search

ag-mailcrypto / storm-plugin

Thunderbird plugin to implement the STORM encryption concept, not based on enigmail
GNU General Public License v3.0
6 stars 0 forks source link

Document existing and new code #11

Open malexmave opened 11 years ago

malexmave commented 11 years ago

Existing Code, like, for example, the functions in Keyring.jsm, should be documented (Docstrings + comments on non-obvious lines).

I'd propose the usual format:

/**
* Brief description
*
* @param param1: Short description of param 1
* @param param2: Short description of param 2
* @return: Short description of return value and format
*/

We could also think about adding @throws for functions that may throw exceptions, if it ever comes to that, but I would really like to see some basic docstrings for each function so I can tell at a glance what it does.

Discuss (or implement ;-) )

gnomus commented 11 years ago

agree

zetaron commented 11 years ago

I agree, since this is one of the points we criticized at enigmail and said we can do better.

opatut commented 11 years ago

I suggest the following format, and agree on adding @throws, too. Will start implementing now.

http://en.wikipedia.org/wiki/JSDoc

Hint for all those sublime users: install DocBlockr extension, and type /**<CR> in front of a function :)