Is there a good convention for documenting functions/return values? If I just put them in comments on top of function, the alignment is all over the place. 
$\begingroup$ $\endgroup$
1 
- 1$\begingroup$ I would generally recommend the "Code" style cells. They don't have automatic alignment, and generally the code looks much nicer with them, and typing experience is much more predictable and closer to a text editor. I use them for code almost exclusively. $\endgroup$Leonid Shifrin– Leonid Shifrin2017-03-30 21:26:10 +00:00Commented Mar 30, 2017 at 21:26
Add a comment |
1 Answer
$\begingroup$ $\endgroup$
Using a comment is awkward and unnecessary. If you have a very long function, you generally don't want to retrieve the full function later, while programming. Hence use the usage option, which will retrieve merely the usage information you've entered:
generateXY::usage = "generateXY[e_, yvar_, extraDims_, dsize_] here e controls how correlated, ..."; Later, you mere type
? generateXY to get the description, not all the (needless) code.
Simple example:
f[x_] := x^3; f::usage = "f[x] gives the cube of x" Later:
? f f[x] gives the cube of x Moreover
?? f retrieves the full information, should you need it:
f[x_] := x^3; f[x] gives the cube of x 