6

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. enter image description here

Yaroslav Bulatov
  • 7,793
  • 1
  • 19
  • 44
  • 1
    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. – Leonid Shifrin Mar 30 '17 at 21:26

1 Answers1

7

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
David G. Stork
  • 41,180
  • 3
  • 34
  • 96