Tooling support to make it feasible to introduce in larger teams

[thlorenz]

In order for anyone to seriously consider using the jsig standard in a team and thus require any onboarding developers to learn it, the following infrastructure is needed:

• jsig to (md|html) generator -- I know this is controversial, but some of us like to sync our in .js API comments to Readme.mds or wikis
• syntax highlighters -- at least vim, sublime should be a good start
• snippet generators -- for same two editors at least I should be able to generate a jsig doc stub for a given function, to aid in learning, avoid mistakes and type less
• linter -- in order to ensure no invalid docs are committed I'd need to be able to have a linter detect those so I can catch'em in my CI build

[Raynos]

• snippet generators are out of scope. That's editor & workflow specific. I never use snippets so someone else should work on that.
• linter is a really cool idea
• syntax highlighter is a cool idea too
• jsig -> md/html shouldn't be hard.

[grncdr]

so the first thing, is there a parser/grammar already?

[thlorenz]

@Raynos I agree that not all these tasks should be responsibility of the jsig team, I merely enumerated what tools/support would need to exist to consider pushing a team to adopt jsig as a standard.

[junosuarez]

@grncdr Raynos started writing a grammar in https://github.com/Raynos/jsig/blob/master/grammar.bnf

@thlorenz I think each of these ideas is great :) One of the main tenets of jsig is that it should be quick and easy to author by hand and read directly - tooling should support this.

[Raynos]

I did start writing a grammar! https://github.com/Raynos/jsig/blob/master/grammar.bnf I forgot about that.

I would like to get a complete grammar / parser going again.

[Raynos]

So I have a real parser now.

It can parse the min-document jsig definition.

I've dogfooded and defined the AST interface using jsig ( https://github.com/Raynos/jsig/blob/master/docs.mli ).

At this point it would be good to get feedback on the AST structure & more examples / tests. I still have a set of examples I want to write integration tests for.

I have interesting ideas for what I'm going to use the AST for ;)

cc @jden @grncdr @thlorenz

[grncdr]

Very cool! From a cursory glance it looks good to me. Hopefully I can find some time soon to update the Any-DB docs to match the new changes to test out the parser.

[junosuarez]

Great work. I'll take a closer look this after noon :)

[Raynos]

I just updated it again.

It contains lots more tests, including tests for its own type definition ( https://github.com/Raynos/jsig/blob/master/test/integration/jsig.js ).

I also added a cli

npm i Raynos/jsig -g
cat docs.mli | jsig --depth=2

Please file issues if it can't parse your jsig files.

I've been testing it on some of my repos including dom-delegator :)