Should inline comments be included in the spec?

[abstrctn]

Several previous issues (#14 #15) have addressed cases where single-bracket inline comments are confusing, or not flexible enough. Looking through our own use of ArchieML at the New York Times, we discovered that we virtually never use them.

To avoid some of the confusion from #15, and to simplify parsing in general, there are two proposals:

• Making inline comments disabled by default
• Removing inline comments from the spec

Has anyone been using inline comments? If so, what do you think about these options?

[abstrctn]

The latest draft of the spec has removed these, so I'll close this but feel free to leave any lingering thoughts you have here.

[gka]

Yes, please keep some form of inline comments in the spec. I don't care how ugly the syntax is going to be. Let's go for JS style comments, they are pretty easy to type, widely known (among developers at least) and have a low chance of being typed accidentally.

My main use case is if you want to explain a key format.

anchor: 0,0  /* left,top (in pixel) */

[gka]

I really like how you can define the template tags in underscore templates by passing a regex. maybe we could do the same in archieml-js? so anyone could redefine their favorite inline comment style

archieml.options({
                  // regex for /* */ comments 
    commentRegex: /(?:\/\*(?:[\s\S]*?)\*\/)|(?:([\s;])+\/\/(?:.*)$)/gm
});

[abstrctn]

I'm open to this as something opt-in.

My main concern at this point would be creating into a state where .aml files on their own aren't a complete representation of the data, since you need the parsing options as well to fully understand how a document should be interpreted.

We can definitely take a stab at this on a branch of archieml-js and see how it works in practice.

Happy to look at it eventually, but if anyone wants to take a stab at a pull request, this should be pretty self-contained.

[gka]

Well, then let's simply use /* */ an be fine, right? But there's got to be some inline comments, I think.