So, is this is a point in favor of not commenting your Javascript code or using inline docs?
Historically, I preferred to use inline JsDoc style comments as the source of documentation for my public APIs. Recently though, I decided that I didn't like them and that I wanted something better. I was hoping to find some tool that parses my JS to AST, figures out what was being exported (e.g. what was public) and writes a JSON document that I could diff over time, to figure out what was documented and what wasn't (in my external docs). So far, I have found this project called `doctor` which sounded close to what I'm looking for, but it still relies on comments ~ https://github.com/jdeal/doctor ~ So, I might have to write it myself using something like Esprima to get the AST...
As others have said, you can always strip comments in production builds. But I agree that this is utterly silly - I'd like to see a movement to deprecate including comments in parsing at all. Anything that makes use of such a feature is hacky weirdness from the start.
> Function.prototype.toString() should be deprecated anyway. There are very few to no legitimate uses of it that are any better than awful eval() hacks.
The toString() on a function is very useful in more ways than awful eval hacks. The most useful way is how I use it in msngr.js for creating keys for methods that handle events.
So let's say your custom object has a way to handle events. Surely you want to allow more than one method to be hit for each event, right? So internally to your object you keep track of this by the method's contents as a sort of key or hash that always points to that specific method. Then you can remove handlers by simply passing in a method. No requiring special keys or anything to identify a function as a function is its own key.
Make sense? It's most useful for developers who work on frameworks or objects that require some custom eventing that can be used by multiple places.
If you really want to deprecate this functionality then you need to provide a way to hash to create a unique key based on a function itself. The only other way around it is adding more verboseness to the language or event handler calls which doesn't add anymore clarity.
Thank you. So, due to the extra work that is required I'm going to say YES - this is one point in favor of not preferring inline docs.
I think all the dissenters missed that part (about it being "one point" in favor/not in favor). I thought programmers were supposed to be good with subtle details, but it seems like the majority of them lose that ability when talking about religious topics.
If the function is nested within another function, then the comments to document the inner function are going to exist inside the outer function. And having nested functions is a very common scenario in JS.
> So, is this is a point in favor of not commenting your Javascript code or using inline docs?
You can of course strip comments when making builds. In fact you can even write functions of more than 600 chars and get away with it as long as you use a minifier. If you have a minified function of more than 600 chars then that's a bulky function which should instead be split in smaller ones.
Historically, I preferred to use inline JsDoc style comments as the source of documentation for my public APIs. Recently though, I decided that I didn't like them and that I wanted something better. I was hoping to find some tool that parses my JS to AST, figures out what was being exported (e.g. what was public) and writes a JSON document that I could diff over time, to figure out what was documented and what wasn't (in my external docs). So far, I have found this project called `doctor` which sounded close to what I'm looking for, but it still relies on comments ~ https://github.com/jdeal/doctor ~ So, I might have to write it myself using something like Esprima to get the AST...