Comments in jsig

[junosuarez]

I want to explicitly allow JavaScript-style comments to jsig to support the mission of writing great documentation that's readable by humans. For example, the following should parse:

Organization : {
 _id: ObjectId,
 members: Dictionary<ObjectId, Member>
}

Member : {
  _id: ObjectId // UserAccount ID
}

I'm not 100% sure how this would be handled in a mixed-mode document, where jsig is embedded in a JavaScript file in comments. @Raynos, could you offer insight? eg

// (Any) => String // this is a worthless function
function (foo) {
  return String(foo) + "!!"
}

[Raynos]

@jden

I don't know how I would do mixed mode. I don't really use mixed mode much, especially not for anything except documentation

[Raynos]

As for comments we should support // and /* */

I've previously used -- or (* because those were the haskell & ocaml comment syntax, but I've since stopped doing that.

I need to get around to doing syntax highlighting for jsig with text editor support.

[junosuarez]

I'm fine with not having mixed-mode comments, since you already have JavaScript comments available. I was just wondering if there's some magic parser body-of-knowledge thing that is conventional or makes sense from a consistency standpoint.

[tomek-he-him]

How about

/* jsig
 * A worthless function
 *
 * (Any) => String
 */
function (foo) {
  return String(foo) + "!!"
}

// A worthless function
// jsig (Any) => String
function (foo) {
  return String(foo) + "!!"
}

The jsig prefix could put other contributors on the right track. It’s a convention used by others, e.g. jsHint: http://jshint.com/docs/#inline-configuration.

[tomek-he-him]

I’m also not convinced we need // comments. JsDoc does well without them.

[junosuarez]

JSDoc has optional descriptions for each parameter, which is what I was going after. In jsig we have optional labels which can be used anywhere something is described by a type, eg worthlessFunction: (foo: Any) => excitedFoo: String, but no way to attach longer descriptions in-line.

At a minimum, for the use case of standalone type definition files (not embedded in javascript comments), I'd like some way to add comments to make them usable by people, consistent with the design philosophy that jsig is for humans: easy to write, easy to read- with or without tooling.

[tomek-he-him]

Alright, I get your point. I was wondering about the same thing as I discovered jsig, but didn’t realize that’s what this issue is about.

I can’t think of an easy solution to this yet.