Async: README слишком длинный до npm

Это косвенно связано с # 859. На какое-то время мы хотели переделать документы Async - создать сайт, более похожий на документы Lodash.

Это было бы здорово, вам нужна помощь? Я не знаю, как далеко вы продвинулись по # 859.

Мы не доработали точную стратегию сборки (ожидая увидеть, как сработает аналогичный толчок для документации Lodash). По крайней мере, мы хотим скопировать документы для каждого метода в блок JSDoc в каждом исходном файле (с полными тегами и информацией о типе) с целью их синтаксического анализа и создания на их основе сайта документации.

@hargasinski, нам определенно jsdoc совместимое форматирование в коде, мы будем очень признательны. Я рекомендую делать этот метод по методам. Если вам интересно, я могу создать ветку для работы, чтобы несколько человек могли внести свой вклад в случае необходимости

Загляните на https://github.com/lodash/lodash/blob/master/lodash.js#L8428 -L8470, если ищете вдохновения.

Если мы получим код в состоянии, в котором он задокументирован в JSDoc, я могу создать сайт документации, похожий на ramdas, lazys или lodashs.

@megawac спасибо! Я посмотрю, как это делает lodash. У меня завтра выходной, так что я, вероятно, мог бы потратить много времени на работу над этим. Я отправлю комментарий о том, как далеко я продвинулся.

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

1. Поскольку настоящего конструктора async , следует ли мне продолжать включать тег
2. @megawac Для сайта, как лучше всего задокументировать функции iteratee и callback ? В readme параметры включают имя, например iteratee(item, callback) , но я не думаю, что это сработает с jsdoc. Я делал что-то похожее на пример lodash, который вы связали, и просто @param , например Invoked with (item, callback) . JSDoc сайт рекомендует что - то вроде:

/**
 * Send a request.
 * <strong i="19">@param</strong> {requestCallback} cb - The callback that handles the response.
 */
Requester.prototype.send = function(cb) {
    // code
};

/**
 * This callback is displayed as a global member.
 * <strong i="20">@callback</strong> requestCallback
 * <strong i="21">@param</strong> {number} responseCode
 * <strong i="22">@param</strong> {string} responseMessage
 */

Поскольку настоящего асинхронного конструктора нет, следует ли мне продолжать включать тег

memberOf async точно подойдет. Также, нит: обратите внимание, что это memberOf а не memberof

Для сайта, как лучше всего задокументировать функции итерации и обратного вызова? В readme параметры включают имя, например iteratee (item, callback), но я не думаю, что это сработает с jsdoc.

На самом деле я не совсем уверен, есть мысли @jdalton? Я знаю, что ramda документирует это с помощью специального тега @sig

Также не нужно торопиться с этим, это определенно большая задача, поэтому мы продолжаем заниматься ею. Спасибо, что изучили это!

Парсеры документов обычно обрабатывают этот бит. В противном случае они должны предоставить проанализированный результат для восстановления.

Можно ли легко связать (например) mapLimit и mapSeries с map ? Все, что вам нужно сказать, это то, что это версии с ограниченным параллелизмом. В противном случае будет много дублированных документов и примеров. (Я думаю, что оставить подпись - это нормально)

Привет, просто быстрое обновление, так как я не мог делать никаких коммитов по запросу на перенос в последние несколько дней. Я все еще собираюсь продолжить работу над этим. У меня есть небольшой опыт сети, поэтому я также смотрел на обслуживание lodash сайта выпуска . Я загружу репозиторий с моим прогрессом, как только доберусь до него достаточно далеко. Цель состоит в том, чтобы получить что-то, что можно было бы использовать и в async.

Возиться с созданием документации локально с изменениями http://docstrap.github.io/docstrap/. Мысли @hargasinski & @aearly

Раньше я использовал docstrap, мне это очень нравится! Это чистый шаблон. Есть идеи по теме? Я предпочитаю лазурь или просвет . Сланец тоже хорош, если вы хотите чего-то более темного.

Кроме того, сейчас самое подходящее время, чтобы обратиться к номеру №975? Было бы хорошо иметь логотип для сайта

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

По-прежнему следите за https://github.com/lodash/lodash.github.io/issues/8 и https://github.com/lodash/lodash.github.io/issues/15 - поскольку оба проекта используя JSDoc, мы можем повторно использовать любую принятую ими стратегию.

Логотип может подождать, мы можем использовать «Async» в красивом шрифте, пока не появится хорошая идея логотипа. : stuck_out_tongue_closed_eyes:

@megawac есть ли еще какие-нибудь недавние работы по публикации наших JSDocs? Было бы здорово иметь сайт документации до выпуска 2.0.

Мне не повезло с их сборкой, и я столкнулся с несколькими проблемами, пытаясь правильно скомпилировать jsdocs на моей машине

@ когда планируете выпустить релиз 2.0? @megawac В настоящее время я не могу выделить время, но в ближайшие 2-3 недели у меня будет еще время, чтобы помочь вам поработать над этим. Если вы сможете направить меня в правильном направлении или просто перечислить некоторые проблемы, я мог бы помочь постепенно их устранить.

У нас нет даты релиза - «когда он будет готов». Документация не является жестким требованием, просто необходимо иметь, поскольку некоторые новые методы документируются только через JSDoc.

@hargasinski, в основном, я просто никогда раньше не использовал @jsdoc, и у меня возникли проблемы с его поиском из нескольких файлов. Я не мог понять, как разместить документы на одной странице. Другой проблемой, которую я обнаружил, было правильное отображение реализаций typedef ( queue и cargo ).

О, хорошо, спасибо, я форк репо и немного поиграю с ним, хотя я не смогу сделать много до конца следующей недели. Я выложу обновление, если получу что-нибудь посильное.