此javascript文档样式称为什么？ [英] What is this javascript documentation style called?

问题描述

在socket.io文档中，他们使用的外观看起来不太像javascript（尽管它是一个javascript库）的命名法。

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.

此处的示例： http://socket.io/docs/client-api/ （此页面已更改，因为这是截至2014年的网络存档快照）

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

我几乎可以通过推论弄清楚（尽管我看起来很难理解，因为它看起来很陌生），但是这种风格从何而来？这是来自另一种语言吗（这肯定不是我见过的javascript语法）吗？有名字吗？

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?

仅供参考，提出这个问题的想法来了因为我在SO上向用户介绍了socket.io文档，然后他们回来说不是javascript，我是否有指向javascript文档的链接。我不得不解释说这是javascript文档，只是一种时髦的（非javascript类）文档样式。

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.

推荐答案

由于使用 object.property 代替了该页面，但我记得 Object＃property 样式

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.

它试图解决的问题是，属性/方法可以在构造函数上使用 >例如 Array。 isArray（） 以及 instances 上，例如 ['foo'，'bar']。join（''） 。问题是如何表示后者。有一些相互竞争的表示法，例如

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（），这就是socket.io文档现在使用的


• Array.prototype .join （技术上正确，但是对于任何不知道JS原型如何工作的人，可以说比 Array＃join 更加令人困惑）
  
• Array＃join（），其发明明显不同于 Array.join 语法，并避免与任何现有的JavaScript语法混淆。

• 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.

Object＃prototype 语法在10年前有点流行，但最终并没有赢，所以现在遇到它时只是令人困惑。

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.

这篇关于此javascript文档样式称为什么？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！