Question: How do I write inline documentation?

[tomek-he-him]

Separate doc files seem a perfect hit for big projects. But I often have simple APIs for simple 20-LOC modules.

I liked inline jsDocs because of the compact, in-code syntax. Easy to maintain, easy to read. How do I go about writing inline jsig docs?

Perhaps so?

 /* Do awesome things
  *
  * Just describing stuff with *markdown* before there’s a solution
  * to <https://github.com/jsigbiz/spec/issues/47>.
  **
  * (
  *   a: String,
  *   b: (String) => Any,
  * ) => Any
  */
export default (a, b) => b(a)

[junosuarez]

The spec doesn't cover how it's done. In my own usage, I do pretty much exactly what you have shown here - with jsig as the part of the comment closest to (and appearing immediately above) a function declaraction (not sure how to handle additional keywords, but for the sake of argument let's say they're fine), and then any additional free-text comment or description about the function appearing above the jsig.

[tomek-he-him]

The spec doesn't cover how it's done.

Perhaps it should? If I find the time to write a tool mentioned in #33 – or if we want IDEs to support jsig – a standard way of doing things is a must.

For example jsDoc has its /** … */ comments. So my idea with the ** separating the comment from jsig may be confusing and unnecessary.

not sure how to handle additional keywords

You mean things like @api public?

[tomek-he-him]

Hmm, I just had an idea. jsig could just as well be an extension to jsDoc. Another way of describing a function within the jsDoc spec.

 /**
  * Do awesome things
  *
  * Just describing stuff with *markdown* before there’s a solution
  * to <https://github.com/jsigbiz/spec/issues/47>.
  * 
  * @public
  *
  * @jsig
  *   (
  *     a: String,
  *     b: (String) => Any,
  *   ) => Any
  */
export default (a, b) => b(a)

Then we get partial editor support for free!

[junosuarez]

jsig could just as well be an extension to jsDoc

afaik jsdoc does not define how to extend jsdoc- any change to that would have to be made to the jsdoc spec.

I'm open to adding a section to the jsig spec on how to embed jsig inline in javascript files. I don't want to require a certain type of comment (/* */ or //). Here is an example of an inline-annotated source file which should be considered valid: https://github.com/jden/funderscore/blob/master/index.js

Note that it introduces types which are used further down in the file.

[tomek-he-him]

jsdoc does not define how to extend jsdoc

But still – by convention – a lot of people and some popular documentation tools add tags not covered by the spec. That’s what I meant – a convention, not an extension.

I don't want to require a certain type of comment (/* */ or //).

Do you plan to make these comments parsable by tools? Like tern, webStorm or the late closure compiler? If so, there must be an easy way for these tools to distinguish between:

// I (just: Like) => Arrows
const something = completely.unrelated;

…and real jsig comments.