details - утилита по поддержанию детальной документации в актуальном состоянии

И чем это лучше javadoc?

Благодаря ей я легко вспомнил все детали и легко продолжил проект.

Я считаю, что технические детали можно включить в сам код. Во-первых, он должен быть самодокументируемым. Во-вторых для исключительных или сложных моментов есть комменты и встроенная документация. А вот бизнес-логика уже пишется вне кода. Там и UML и остальное включается. И вот твоя утилита не решает ни одну из этих проблем. Потому что источник проблем - само желание описывать код красиво и чотко. Без этого ни одна утилита тебя не спасет.

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

Ещё.. Лучше javadoc хотя бы тем что не только для java. В текущем виде правда не для Perl, но не долго исправить.

И.. знаем мы ваш самодокументируемый код. По моему опыту самая главная проблема хакера начинается тогда когда функция вызывает функцию, та третью и когда уровней становится больше 5 ничего уже не разобрать без глубоких знаний деталей проекта. На мой взгляд детальная документация позволяет очень удобно пояснять код именно в том объёме который необходим для понимания кода. А разбирающемуся удобно по имени детали вспоминать: «ага, эту деталь я уже читал, значит пойму».

Ещё вспомнил. Вы говорите лень. Детальная документация может не решает эту проблему абсолютно, но подстёгивает. Дело в чём? Расставить @метки - дело не сложное и тогда даже не задумываешься какой это объём документации. А когда метки уже расставлены, может и лень всё описывать, но ты как контракт с собой подписал.. Сидишь, матюкаешься, но описываешь… Зато потом какой кайф это всё читать когда нужно что-то вспомнить..

Чем doxygen не нравится?

API описать можно в чём угодно. В двух словах что делает функция описать легко хоть в комментариях.

Детальная документация не про то. Не про то «что» делает функция, а именно про то «как» она это делает.

А когда метки уже расставлены, может и лень всё описывать, но ты как контракт с собой подписал

Три раза ха. Если код неактуален, тесты и тестировщики заставят автора привести его в порядок. А вот дока != контракт. И если она изменится или устареет, что ты будешь делать, кому будешь верить, доке или коду? Если все равно в коде ковыряться, то дока становится как минимум лишней. Ну вот у тебя было 3 месяца и 1 автор, почти тепличные условия. А поработай среди рукожопов с десяток лет...

А есть ссылка на саму эту систему?

Чем лучше/хуже Doxygen?

Не про то «что» делает функция, а именно про то «как» она это делает

И тут не понимаю. Если надо принять/отправить контракт, то в чем непонятность и потребность детального описания. Может не стоит методы писать на 3 страницы и спагетти-код?

знаем мы ваш самодокументируемый код

Вот в том и дело, что есть сомнение.

кому будешь верить, доке или коду?

А вот тут самое интересное. Код сильно меняется как правило если переписывается. При этом стираются и все метки на детали и расставляются новые которые надо заново описать. Для этого эта утилита.

А если изменения косметические то программист уже сам ответственен за правку и детали если он правит код под ней.

Но вы правы в больших масштабах я ещё не испытывал. Но уверен что и там найдутся свои преимущества у детальной документации.

По ссылке всё. Скрипт, а скрипт сам покрыт детальной документацией. Т.е. это одновременно и пример применения.

Может не стоит методы писать на 3 страницы и спагетти-код?

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

А, так это ты свою штуку пиаришь. Оке.

Спасибо. Посмотрим.

Сравнивать надо кстати не с Doxygen, а с Literate Programming.

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

Помогли бы въехать скриншоты процесса работы или гайд.

По ссылке всё. Скрипт, а скрипт сам покрыт детальной документацией. Т.е. это одновременно и пример применения.

И тут я вошёл в рекурсию. Чтобы понять как пользоваться утилитой, надо прочитать инструкцию к ней, но при этом сама инструкция является примером использования! Как теперь выйти?

Помогли бы въехать скриншоты процесса работы или гайд.

На самом деле действительно сложно объяснить даже что это есть. Вот сегодня пытался другу объяснить. Его словами когда он уже понял:

Это справочник с документацией по коду, на главы которого мы ссылаемся в комментариях.

И тут я вошёл в рекурсию. Чтобы понять как пользоваться утилитой, надо прочитать инструкцию к ней, но при этом сама инструкция является примером использования! Как теперь выйти?

Легко же! Дело в том, что пример использования не является инструкцией утилиты. Пример использования - это пояснение того как утилита работает. А инструкция - в usage секции README. И утилита анализирует пример использования. Только пример использования вовсе не утилиты, а системы документации, поэтому рекурсии нет.

Короче ничего всё равно не понятно.. Тут ещё выяснилось что пример использования крайне неудачный и заставляет думать будто это справочник команд Bash. Чтобы было понятней о чём могут быть детали приведу пример моей любимой детали из другого проекта:

https://github.com/unDEFER/hexpict/blob/master/details/ru/H.md#hypermask

К ней я обращаюсь весьма часто, потому что запомнить номера всех форм весьма сложно, хотя они и закономерны.

Без интеграций с редакторами/гитхабом/гитлабом не взлетит точно. Да и с ними тоже вряд ли.

Literate Programming действительно не взлетел, по означенным в README причинам.

У этого мне кажется шансов больше. А интеграцию запилят только если взлетит, это понятно..

А интеграцию запилят только если взлетит, это понятно..

Ну оно не взлетит, пока не напишут интеграции под самые популярные тулзы. А никто со стороны не будет пилить, пока не взлетит. Проблему видишь? :)

Так даже если я напишу такую интеграцию кто её включит в основную ветку пока не взлетит?

А зачем «включать в основную ветку»? У большинства популярных IDE/текстовых редакторов обычно есть возможность без особых проблем устанавливать сторонние плагины.

Детальная документация не про то. Не про то «что» делает функция, а именно про то «как» она это делает.

Что функция делает, обычно понятно по имени или докстрингу (если он есть, конечно); в крайнем случае по коду. Как она это делает, знать особенно незачем, если мы не ковыряем конкретно эту функцию. Меня обычно больше интересует, зачем она делает то, что делает, смысл ее существования и место в общей картине.

Генераторов доки из кода много разных есть, но те, что я видел, предполагают, что код с доками в одном файле как-то соседствует. Хранить исходники доков для генератора отдельно от кода — любопытный подход.

Пишите, пишите. Как заметили выше, не хватает плагина, который можно поставить одной кнопкой в любимую ИДЕ и потыкать. И красивых гифок с записью работы с ним.

Кажется наконец понял что вы сделали, это как аннотации в пдф но к коду, и может что-то подобное уже было здесь:
https://marketplace.visualstudio.com/items?itemName=cyberbiont.vscode-sidenotes
или здесь:
https://marketplace.visualstudio.com/items?itemName=tkcandrade.code-annotation

Кажется наконец понял что вы сделали, это как аннотации в пдф но к коду, и может что-то подобное уже было здесь: https://marketplace.visualstudio.com/items?itemName=cyberbiont.vscode-sidenotes

Вот да, там и исходники есть, в которых можно подсмотреть основные моменты работы с редактором.

Кажется наконец понял что вы сделали, это как аннотации в пдф но к коду, и может что-то подобное уже было здесь:

Ну не совсем. Аннотации как я понял это что-то для себя, а у меня документация для любого читателя кода.

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

Это справочник с документацией по коду, на главы которого мы ссылаемся в комментариях.

Помнишь был такой thelp.exe под DOS? По функциям MS-DOS, BIOS и т.п.?

Классная штука была в своё время.

Спасибо за работу, думаю посмотреть в своё время.

Теперь и у меня сомнения что ты понимаешь что такое «самодументированный» код

Я понимаю. Типа когда функции короткие и хорошо названы то можно и комментарии не писать.

Но смысл создавать единично используемую функцию и чем это лучше комментария?

Типа когда функции короткие и хорошо названы то можно и комментарии не писать.

К любому «самодокументируемому» коду один хрен нужна документация. Код (граф вызовов) — это (обычно немаленькое) дерево, лазить по нему туда-сюда можно до умопомрачения. Чтобы быстро вникнуть в суть, нужна старая добрая линейная история, последовательное изложение.

Типа когда функции короткие и хорошо названы то можно и комментарии не писать.

Напомню ещё про Ctrl+F1 ;)

смысл создавать единично используемую функцию … ?

• вызов функции легче читается чем комментарий и куча строк под ним.
• Часть локальных переменных уйдет из большой функции и читать ее станет легче.
• Проще тестировать

вызов функции легче читается чем комментарий и куча строк под ним.

А я понял.. Типа у комментариев нет скобочек.

Часть локальных переменных уйдет из большой функции и читать ее станет легче.

А если список аргументов чтоб выделить функцию километровый? Создавать ещё кучу не нужных сущностей в виде структур?

Проще тестировать

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

Но надо сказать что входы у таких функций зачастую не простые и в отрыве от функции вызывающей сгенерировать их довольно не просто.

Напомню ещё про Ctrl+F1 ;)

Я не знаю что это. И релевантного ответа не нагуглил.

Контекстный help в Delphi 2.

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

Поддержать переход от кода к документации можно в IDE, и раскраску покрытия тоже. Т.е. если документация есть, рисовать одним образом, если нет, то другим (например подчёркивать красным волнистым?)

Ого! Соавтор идеи наметился!

Честно, до этого я ещё не додумался. Готов не только поддержать вашу идею всеми руками-ногами, но и стартовать лучшую реализацию по вашему с нами мнению как можно скорее.

Да не, я просто пытался скомпилировать библиотеку, написанную в стиле literate programming. И поискал эти два слова на LOR

В смысле? Какие два слова? Прям «детальная документация»? А как вы додумались до такого запроса? Не вижу из вашего контекста упоминания чего-то подобного.

Всё, понял «literate programming» на LOR вы искали.

два слова это «literate programming». они есть в этом топике выше. догадался до этих слов прочитав документацию к библиотеке libavl вообще и утилите TexiWEB которая там внутри в частности. Но сам факт того, что я не могу скомпилировать этот проект меня очень печалит и LOR пока не смог помочь.

для того, чтобы написать редактор/IDE, мне были бы интересны технологии PWA или JavaFX (меньше). Но это настолько неподъемная задача, что я бы не рискнул. Так, только чуть поговорить на тему.

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

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

Так, давайте опишите ещё раз в кратце суть вашей проблемы. Я имею опыт обращения с literate programming проектами мне многое можно не разжёвывать.

Давайте же, давайте отложим формальности и перейдём непосредственно к обсуждению сначала. А то может и вписывать ничего не прийдётся.

Сначала вашу проблему порешаем тогда.

ну. у меня две проблемы:

1. понять, как скомпилировать libavl (там не работает утилита makeinfo из пакета texinfo, наверное она слишком новая, с новыми багами)
2. иметь способ литературно программировать без недостатков libavl (т.е. чтобы код не был замусорен, а документация чтобы в .pdf собиралась)

Понял. Если я правильно понял логику этого сообщения, то @ end в нём именно означает «окончание строки», или даже «отсутствие закрывающей скобки в конце при наличии открывающей» и должно чиниться примерно так

Было:

At the bottom of section 19 you will find a note reading `@little{This
code is included in @segno{15}.}', making it easy to move back to

Действие: подшаманили с переводом строк

Стало:

At the bottom of section 19 you will find a note reading
`@little{This code is included in @segno{15}.}',
making it easy to move back to

Попробуйте.

Второе. details - он именно об этом. Улучшенная, более продвинутая версия literate programming без его фатальных недостатков, из-за которых он не может и не мог никогда взлететь кроме как у пары авторов-одиночек, пишущих проект с нуля и с самого начала вдруг жёстко решивших заморочиться чтобы документация была именно в Literate стиле.

Посмотрите другие примеры использования details, например:

https://github.com/unDEFER/h6pedit

Обожаю гексагональную графику, OpenHex - моя любимая игра (только жаль AI не апгрейдит юниты).

Ого! Вы и об этой идее имеете своё представление! Ну вы явно не случайно оказались на этой странице :-)

Так какое теперь сообщение от libavl?

Рисуем хорька в гексагональной графике

А у меня ещё есть древнейший проект аля-настольной компьютерной логической игры происходящей на узлах гексагональной решётки, у которой я никак не могу докрутить правила игры :-) 12C называется, лежит у меня описание правил подробное в загашнике, никуда не выкладывал именно по причине недодуманности.