1

In java we generally do it the java-docs way and in js the popular method these days is vscode documentation using @param, @returns, @example etc but I would prefer if there were some language agnostic and IDE agnostic way to do so; probably, backed by some RFC; anyways, the most I can come up with is using markdown which seems to work for me but I'm not sure that's why reaching community to find out if we already have some standard way to do this

anyways the following

/**
 * returns random string of *length* e.g. generateRandomString(6) can return 'fi3Y0s'
 * 
 * - **Parameters**:
 *   - `length` {number}: required length of random string 
 * 
 * - **Returns**:
 *   - {string}: string consisting of random characters and having length provided by _length_ parameter
 * 
 * - **Example**
 *   ```javascript
 *   generateRandomString(6)
 *   //fi3Y0s
 *   ```
 */
function generateRandomString(length) {
  // implementation goes here
}

would yield this is vscode which is convincing enough enter image description here

which kind of works except the function definition line still show wrong parameter type but it's okay; now, apart from this I'd like to know if I can do better so that other developers are also cool with it

What I tried: googling, chatgpt (that's where I got the markdown idea); there were guides but about what to document rather than about how to type this documentation; also I could not find any RFC on this, Now my expectation is some RFC if exists or some unspoken virtual standard which is shared by the community, something backed by open-source standards

(I didn't ask this question on stackoverflow because if was hinted to be subjective, just wanted to confirm if there's already something existing just like REST standards and I'm just not aware about it)

Doc Brown
  • 218,378
Raven Danish
  • 41

2 Answers2

7

There is no standard. It all depends on the specific tool that you use for generating the documentation.

On one hand, you have language-specific tools like Javadoc for Java, Scaladoc for Scala, rdoc for Ruby, and pydoc for Python, to give a few examples. You also have tools that support multiple languages, like Doxygen.

You need to consider your environment and choose the appropriate tool(s). If I need a documentation generator, I start with a tool that comes with the language, if one exists.

Thomas Owens
  • 85,641
  • 18
  • 207
  • 307
1

This has interested me as well ever since I discoverede first "literate programs" and then Bird Style first in Miranda and then Haskell. See https://wiki.haskell.org/Literate_programming#Bird_Style

To make a long story short, we ended up using AsciiDoc which is very similar to Markdown but has a very useful feature, namely being able to include tagged regions from files - https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/ which allows us to include live source code snippets. The IntelliJ and Visual Studio Code plugins renders this automatically - unfortunately Github supports AsciiDoc but not this particular feature.

This allows us to have a README-foo.adoc file that dynamically pulls out source snippets in context when rendered and then full documentation can be provided there. This has worked very well for us so far. For sources the asciidoc file can be put in the same folder as the sources documented, and then the root README.adoc can link to these as needed.

Thorbjørn Ravn Andersen
  • 1,347
  • 10
  • 14