Как читать документацию фреймворков javascript?

Question

Исходя из мира .NET. У меня есть сложная документация для фреймворков javascript. В качестве примера я возьму «Node.js MongoDB Driver API». Существует объект Collection, который имеет метод count(). Вот ссылка на него: http://mongodb.github.io/node-mongodb-native/2.0/api/Collection.html#count

Оттуда я вижу, что count() принимает три параметра:

count(query, options, callback) 

Сначала я думал, что я должен предоставить все три из них для того, чтобы использовать этот метод. Тем не менее, в примере кода для этого метода я вижу, что он иногда использует только один, а иногда только один параметр:

// Perform a total count command 
collection.count(function(err, count) { 
    test.equal(null, err); 
    test.equal(4, count); 

    // Peform a partial account where b=1 
    collection.count({b:1}, function(err, count) { 
    test.equal(null, err); 
    test.equal(1, count); 

    db.close(); 
    }); 

В первом случае она вызывает подсчет() только с callback параметром а во втором оно обеспечивает options и callback. Нет примера использования всех трех параметров, как указано в описании исходного метода.

Мой вопрос в том, как можно знать такие вещи? Я имею в виду, если бы в этой документации не было примеров, как бы я знал, что это будет возможно? Также как я могу быть уверенным, что есть другие возможные способы использования метода, если это не покрывается примерами, подобными этому?

Я знаю, что вполне законно вызывать функции javascript только с предоставленными некоторыми параметрами, и функция должна иметь возможность обрабатывать его на основе реализации. Но, как потребитель API, я не хочу заглядывать в реализацию функции, чтобы выяснить, какую комбинацию параметров я могу пройти. Мне кажется, что эта документация не завершена (я взял этот драйвер mongodb как пример, но я столкнулся с подобной проблемой с другими документами js framework).

Есть ли какие-то рассуждения, которые я должен иметь при чтении документации по javascript, как думать об этом при попытке понять API разных фреймворков, как узнать, что возможно, а что нет и т. Д.??

Answer 1

В JavaScript и особенно в мире Node.JS существует общий шаблон для асинхронных функций, поскольку их последним аргументом должна быть функция обратного вызова.

count(query, options, callback) 

При вызове функции асинхронной, вы должны предвидеть, что результат вызова придет обратный вызов иначе как бы получить результаты вашего вызова функции асинхронного? так что на основе вышеприведенного утверждения вы должны по крайней мере предоставить функцию обратного вызова методу подсчета и другим функциям async, которые вы вызываете в JavaScript.

Другое дело, что может помочь вам, когда вы видите методы MongoDB является то, что он является общим, что если вы собираетесь обрабатывать некоторые данные с базой данных, необходимо обеспечить, по крайней мере объект запроса и обратного вызова функции, но если вам нужна дополнительная информация по вашему запросу, вы предоставите объект объектов.

Я знаю, что документация не хорошо объяснить, если параметры запроса и опции являются опциями, но если вы видите исходный код count method и читать мои комментарии добавлен код, который вы могли понять:

Collection.prototype.count = function(query, options, callback) { 

    // args represents the three parameters 
    var args = Array.prototype.slice.call(arguments, 0); 

    // extract your last argument and assumes that it is the callback function 
    callback = args.pop(); 

    // extract the first argument that is query 
    query = args.length ? args.shift() || {} : {}; 

    // extract the second argument but this time shift already extracted query 
    // so the first parameter this time will be options. 
    options = args.length ? args.shift() || {} : {}; 

    ... 
} 

если вы пройдете следующие значения вызова, вы увидите порядок комментировал в том, как метод подсчета собирается захватить аргументы:

count({}, {}, function callback() {}); // count(query, options, callback) 
count({}, function callback() {}); // count(query, callback) 
count(function callback() {}); // count(callback) 

на самом деле в вашем примере, что вы предоставили во вложенном вызове считать метод , вы передает запроса и обратный вызов и не входящие в опцию и обратный вызов к методу подсчета:

collection.count(function(err, count) { 
    test.equal(null, err); 
    test.equal(4, count); 

    // You are passing the values in this order (query, callback) 
    // {b: 1} === query 
    collection.count({b:1}, function(err, count) { 
    test.equal(null, err); 
    test.equal(1, count); 

    db.close(); 
}); 

Я надеюсь, что это объяснением и код поможет вам понять эту общую картину обратных вызовов по всему миру JavaScript.