You should be more specific what you mean by JSDoc – this is a generic term covering pretty much all the JavaDoc-style documentation tools for JavaScript. The syntax you used for array of strings looks like the one supported by Google Closure Compiler. Using this, an array of Objects would be: /** * @param {Array.<Object>} … Read more
Have a look at the reStructuredText (also known as “reST”) format, which is a plaintext/docstring markup format, and probably the most popular in the Python world. And you should certainly look at Sphinx, a tool to generate documentation from reStructuredText (used for eg. the Python documentation itself). Sphinx includes the possibility to extract documentation from … Read more
Here is an example of all the options I have found as of Xcode 5.0.2 That was generated with this code: /** First line text. Putting \\n doesn’t create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character! @a Italic … Read more
Think about somebody doing help(yourmodule) at the interactive interpreter’s prompt — what do they want to know? (Other methods of extracting and displaying the information are roughly equivalent to help in terms of amount of information). So if you have in x.py: “””This module does blah blah.””” class Blah(object): “””This class does blah blah.””” then: … Read more
Since docstrings are free-form, it really depends on what you use to parse code to generate API documentation. I would recommend getting familiar with the Sphinx markup, since it is widely used and is becoming the de-facto standard for documenting Python projects, in part because of the excellent readthedocs.org service. To paraphrase an example from … Read more
B business day frequency C custom business day frequency (experimental) D calendar day frequency W weekly frequency M month end frequency SM semi-month end frequency (15th and end of month) BM business month end frequency CBM custom business month end frequency MS month start frequency SMS semi-month start frequency (1st and 15th) BMS business month … Read more
Well, since this is about comments and code, let’s look at some actual code. Compare this typical code: float a, b, c; a=9.81; b=5; c= .5*a*(b^2); To this self-documenting code, which shows what is being done: const float gravitationalForce = 9.81; float timeInSeconds = 5; float displacement = (1 / 2) * gravitationalForce * (timeInSeconds … Read more
You can use // MARK: There has also been discussion that liberal use of class extensions might be a better practice anyway. Since extensions can implement protocols, you can e.g. put all of your table view delegate methods in an extension and group your code at a more semantic level than #pragma mark is capable … Read more
Formats Python docstrings can be written following several formats as the other posts showed. However the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in this blog post. Note that the reST is recommended by the PEP 287 There follows the … Read more
You can use triple-quoted strings. When they’re not a docstring (the first thing in a class/function/module), they are ignored. ”’ This is a multiline comment. ”’ (Make sure to indent the leading ”’ appropriately to avoid an IndentationError.) Guido van Rossum (creator of Python) tweeted this as a “pro tip”. However, Python’s style guide, PEP8, … Read more