jsigbiz / spec

JavaScript signature notation
130 stars 6 forks source link

Comments in jsig #47

Open junosuarez opened 9 years ago

junosuarez commented 9 years ago

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 commented 9 years ago

@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 commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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

junosuarez commented 9 years ago

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 commented 9 years ago

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.