3

In the socket.io documentation, they use a nomenclature that doesn't look like javascript (though it's a javascript library) that seems a bit out of place.

Examples here: http://socket.io/docs/client-api/ (the page has changed since, here's a web archive snapshot as of 2014)

This one is clear enough (just specifying types of arguments and return value):

IO(url:String, opts:Object):Socket

But this style I don't recognize at all:

IO#protocol
Manager#timeout(v:Boolean):Manager

I can pretty much figure it out through deduction (though I find it hard to read because it looks so foreign), but where does this style come from and why? Is this from another language (it certainly isn't javascript syntax that I've ever seen)? Is there a name for it? Is there a description of this style of documenting objects, methods, properties?

FYI, the idea to ask this question came because I referred a user here on SO to the socket.io documentation and they came back and said that wasn't javascript, did I have a link to the javascript documentation. I had to explain that it was the javascript documentation, it was just a funky (non-javascript-like) documentation style.

Nickolay
  • 31,095
  • 13
  • 107
  • 185
jfriend00
  • 683,504
  • 96
  • 985
  • 979

1 Answers1

1

The page in question has been rewritten since to use object.property instead, but I remember that Object#property style, though I don't think it's ever had a name.

The problem it's trying to solve is that properties/methods can be available on constructors like Array.isArray(), as well as on instances, like ['foo','bar'].join(' '). The question is how to denote the latter. There were some competing denotations, such as

  • array.join(), which is what the socket.io docs are using now
  • Array.prototype.join (technically correct, but arguably even more confusing than Array#join to anyone who doesn't know how prototypes work in JS)
  • Array#join(), invented to be clearly different from Array.join syntax, and to avoid confusion with any existing JavaScript syntax.

The Object#prototype syntax was somewhat popular ten years ago, but didn't win in the end, so now it's just confusing when you encounter it.

Nickolay
  • 31,095
  • 13
  • 107
  • 185