Sinon: Документация по стилю "Спецификация API"

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

В Java есть автоматические инструменты для создания JavaDocs без ручной работы. Чтобы добиться чего-то подобного в библиотеке JS, требуется тонна ручной работы. Я бы хотел увидеть что-то подобное, но боюсь, что оно быстро устареет.

Мы могли бы немного поговорить об аннотациях кода и инструментах. Может есть жизнеспособные варианты.

Я знаю, что это поднималось в других потоках, но я думаю, что очень просто, что вся библиотека должна быть задокументирована с помощью jsDoc. Это своего рода стандарт для JavaScript (или, по крайней мере, самый веский аргумент в пользу этого). Мы могли бы просто опубликовать api, начиная с минимального объема документации, и повесить на стену большой знак «в процессе» и строить оттуда.

@mantoni Существует множество инструментов для автоматического создания JSDoc. Я не вижу проблемы с v1. Вам не нужно создавать везде @typedef s. Просто имея

/**
  <strong i="8">@param</strong> {String} [foo] optional string
  <strong i="9">@example</strong> Create foo instance
       var foo = dooFoo('somestring') 
*/ 

помогло бы совсем немного.

Привет @ 76784 , отличный вклад! 😊

Однако у меня есть несколько соображений.

Мне очень нравится JSDoc. Это также то, что мы используем в Chai.js и до сих пор это работало довольно хорошо благодаря возможности разделять вещи на пространства имен и всегда поддерживать синхронизацию кода с документами, поскольку они находятся рядом друг с другом.

Однако я не согласен с тем, что документация по Java является «золотым стандартом». Я считаю, что документы Java очень сухие. Это хорошо для справки, но плохо для изучения или осмысления большей части. Мне нравится то, что документы для Sinon написаны в дружественном классическом стиле с открытым текстом. IMO, который помогает стимулировать усыновление Кроме того, в качестве справочника по API они довольно хороши, IMO.

Я думаю, конечно, было бы хорошо иметь JSDocs, но важно отметить, что это потребует чрезвычайно значительных усилий.

Если бы @ 76784 запустил ветку и

@lucasfcosta

Я считаю, что документы Java очень сухие. Это хорошо для справки, но плохо для изучения или осмысления большей части.

Я не согласен. Я просто говорю, что две вещи - документация и руководство - должны быть разными. Сухость javadocs - плюс. Можно пойти туда и выяснить, через это соглашение на сухом языке, _ что_ делает "вещь". И, конечно же, самое главное, носит комплексный характер. Мне не нужна многословная структура предложений в моей документации - я хочу это в моем руководстве.

Я не эксперт в JSDoc, но мне интересно, есть ли в комментариях JSDoc простой способ ссылки на учебник для записи.

Что касается предоставления некоторых доказательств концепции по этому поводу , момент у меня немного не хватает времени (я знаю, а кто нет?), Но, возможно, я буду в лучшем положении, чтобы позже в этом году . Это был бы отличный способ досконально изучить Синон.

Эта проблема была автоматически помечена как устаревшая, поскольку в последнее время не было активности. Он будет закрыт, если больше не будет активности. Спасибо за ваш вклад.

Я закрепил эту проблему, поэтому она не закрывается устаревшим ботом

Если мы все же решим пойти по этому пути, то, я думаю, нам следует использовать что-то вроде https://github.com/gajus/eslint-plugin-jsdoc ... правила, вероятно, должны войти в eslint-config-sinon .

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

Когда я смотрю на что-то вроде шпионов: https://sinonjs.org/releases/v7.4.1/spies/

Я работаю с Mocha, синтаксис которого отличается от синтаксиса, показанного в первом фрагменте.

"test should call subscribers on publish": function () {
    var callback = sinon.spy();
    PubSub.subscribe("message", callback);

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

Тот факт, что я использую мокко вместо того, что есть (жасмин?), Не имеет большого значения . Они явно похожи. Но что действительно делает этот пример трудным для понимания, так это то, что вы не показываете тестируемую функцию.

Я думаю, что это следует сделать, если вы собираетесь приводить примеры. Покажите минимальную работоспособность того, что тестируется. Та же проблема здесь, с myLib : https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

Я понял - myLib - это то, что я бы написал. Но вы просите многих новичков изучить эти вещи, не видя ничего из того, против чего они тестируют.

На самом деле этот тест ЯВЛЯЕТСЯ использованием синтаксиса Mocha, вы просто используете более стандартный стиль BDD (из двух) :-) Он также используется некоторыми другими библиотеками, такими как Buster JS, который (совместно) создал оригинальный создатель Sinon. В любом случае, для кого-то, вероятно, имеет смысл обновить все примеры до наиболее распространенного стиля использования :-)

Что касается других моментов, то они вполне актуальны, и мы это уже обсуждали. Фактически, мы обсуждали наличие запускаемых, протестированных, встроенных примеров, гарантирующих достоверность. Что косвенно устранит эти проблемы. Но да, кому-то нужно сесть и сделать это ...

На самом деле этот тест IS с использованием синтаксиса Mocha

Какие?? Теперь я собираюсь разглагольствовать о документации Mocha. :-)

Я попытался начать это усилие на https://github.com/sinonjs/samsam/pull/82. Ваши комментарии приветствуются, пожалуйста, разместите их в этом PR.