Всем привет!
Мы тут выпустили небольшой тул для Javascript разработчиков, который позволяет автоматом создавать документацию для проекта (не путать с API) duckdoc.io. Народ, гляньте и дайте обратную связь, пожалуйста.
Всем спасибо!
Вероятно штука полезная, может даже удобная. Имхо, большей полезностью обладает решение задачи по связыванию описания кода с документами постановки задач, позволяющая понять, «как поставка превратилась в код». И сопутствующая задача, актуализация документации по результатам вносимых изменений (как постановки, так и того, что из нее следует... код, форматы, регламенты и прочее «системное»). На сегодня это все скорее вопрос «войны» а не «мира» между «постановщиками» и «исполнителями» )
А смысл? Хорошо-написанный код — вполне достаточно самодокументируем.
Эм, видно я не догоняю, но чем это отличается от jsdoc и ему подобных? Оно само бабельный AST анализирует и делает предположения о типах или руками вписывается потом?
@param {(’farfalle’|’penne’|’spaghetti’)} pastaType — The allowed type of the pasta
как бы более информативно.
Оно само бабельный AST анализирует и делает предположения о типах или руками вписывается потом?
Вписывается руками.
Отличие от jsdoc небольшое. Если команда уже использует jsdoc формат, и какой-либо генератор для статических файлов с документацией, в принципе этот тул особо может и не быть нужен.
Но, jsdoc формат может так же быть использован и с этим тулом. Но помимо того что генерирует jsdoc, он позволяет вписать дополнительную информацию руками, которую в том же jsdoc делать либо неудобно, либо в принципе невозможно. А еще он по факту не обязателен, можно иметь обычные комментарии кода, по типу godoc, или не иметь комментариев в коде в принципе. Тул так или иначе сгенерит основу, которую можно будет использовать как базу для доки.
Ну тогда не ясно какие новые задачи он решает, или что решает лучше или проще... Вокруг jsdoc уже давным-давно сформировано комьюнити, плагины, поддержка IDE (но грабли с документированием перегруженных функций в самой IDE), вероятно, позволяет делать то же самое, а то и больше. Ну и само собой инструменты под организацию CI/CD, потому никаких проблем в поддержке синхронизации доков с кодом нет, никакой консольный тулз запускать не надо «Run it every time you finish writing code». Еще и под MIT. В jsdoc ничего же не мешает что угодно вписывать в комменте в качестве описания, @description/@example/@see- кажется покрывают все задачи. Markdown там поддерживается из коробки.
Если там все сводится к обходу FunctionDeclaration&FunctionExpression и вытягиванию с их поддерева аргументов, чтобы описание потом подставить, то выглядит не очень полезным. Но кто знает что там на самом деле...
не совсем понятно откуда берутся описания методов и аргументов из
static.tildacdn.com/...034-633463346464/code.svg
сюда
static.tildacdn.com/...b934-373331333330/doc.svg
artificial intelligence ?
Добрый день, аргументы определяются автоматически путем простого парсинга.
А описание для них добавляет человек, после запуска команды и генерации ченджсета.
Потому нет, тут нету AI. :)
Дмитрий Демьяненко
Мокий Парменыч
Dmitriy Mozgovoy
Vladyslav Hrytsenko
Dmitriy Mozgovoy
Alex Furman
7 комментариев
Добавить комментарий Подписаться на комментарииОтписаться от комментариев