В каком формате вы пишете документацию к своим проектам?

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

1. Тупо комментарии в коде.

2. Что-то более сложное отдельным файлом в ./docs/

Для большой документации AsciiDoctor. Но это отдельная история.

Что-то более сложное отдельным файлом в ./docs/

Вот поэтому я и решил пилить документацию.

А почему например не в LibreOffice?

И где его хранить?

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

// Проверяем не следует ли за текущим узлом следующий узел, имеющий такое же имя.
// Если да, то считаем, что это группа узлов является динамическим массивом.
//
    flDynArray      = 0;
    pCurNodeXMLTemp = pCurNodeXML->NextSibling();

    if ( pCurNodeXMLTemp ) {

     if  ( Metastrcmp( pchNameCurNodeXML, pCurNodeXMLTemp->Value() ) == 0  )
      flDynArray = 1;                                      // == 1 - Эта группа узлов является динамическим массивом

    }

Без комментариев пришлось бы тратить время на понимание предназначения кода.

AsciiDoc, у него возможностей побольше чем у markdown

Если генерить из исходников, то можно посмотреть Doxygen

Сам пока поглядываю в сторону markdown, т.к. в нём в нём есть подсветка и можно вставлять картинки

Ты же даже не отличаешь формат от его визуализации. Markdown - формат текстовый, там нет и не может быть не подсветки, ни картинок, они будут только если его отрендерить, и то смотря куда и чем.

Отвечая на конкретный вопрос - конечно же Markdown, он достаточно простой, достаточно умеет и везде поддерживается. Однако важнее где хранить и как рендерить. Мы храним документацию для разработчиков прямо в коде в виде rustdoc, и когда нужны иллюстрации используем псевдографику, а не картинки. Не знаю можно ли там вообще картинки, если и можно то кажется что это будет неудобно. Псевдографику же видно и прямо из кода, и в отрендеренном html. Для пользователей документация в виде дерева .md файлов, которое рендерится readthedocs.io или его аналогами.

Воспользуйтесь подходом системы автоматизации документирования «Стрела»:
https://upforme.ru/uploads/0018/41/1a/73/330938.jpg

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

Воспользуйтесь подходом системы автоматизации документирования «Стрела»:

В те года много интересных разработок было.
Например технология визульной разработки (это не Dragon, uml, …).
Весьма удобная технология.

Для помощи написания можешь воспользоваться современными возможностями llm – deepwiki или deepwiki-open. llm делает множество разных вызовов, анализирует проект, чертит схемы и таблицы.

Не, мне стильно-модно-молодёжно не нужно: я уже слишком стар для всего этого дерьма :(

И где его хранить?

В проект добавляем директорию, например doc (которая может иметь и поддиректории).
Зато doc LibreOffice можно сконвертироваь и в иные форматы.

Впрочем у меня банальный txt …

я уже слишком стар для всего этого дерьма

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

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

Это в общем случае не так. Посмотрите на экосистему rust - там все крейты замечательно документированы, и всё генерится только из rustdoc. Который, к слову, помимо документации к функциям и типам, позволяет там же, в коде, писать и доку в свободном формате, с введением, примерами и всем прощим, заменяющую README.md (есть даже cargo readme который его генерит. Doxygen то же самое позволяет (только наоборот, обычно README.md засасывает на свою главную страницу). Документацию к библиотекам это покрывает на 100%, к коду приложений на 200% (это я к тому что код приложений сильно реже документируют, но когда да это очень круто).

Не покрыта остаётся только пользовательская документация к приложениям, которая к коду не привязана, по-другому структурирована и может иметь другой формат.

Хотя если говорить конкретно про Doxygen и документирование C++ кода, оно мне субъективно кажется сильно менее приятным чем в Rust. Может потому что doxygen поощряет возню типа документирования аргументов и возвращаемых значений вместо действительно важных вещей, а в результате получается простыня воды оформленная в стиле интернета 90-х, а в rustdoc достаточно нескольких строчек описания и примера, который ещё и тестом сам по себе является. Может если так писать так в Doxygen то это было бы и приятрей, и документация полезней получалась + стиль поменять, но увы уже поздно, сейчас актуален только rust.

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

У таковых опыт есть и скорее могут разработать новые технологии …

В лучшем случае там получится справочник по использованию функций

Как по мне, в в случае Library/API это как раз то, что нужно

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

Doxygen examples

Может потому что doxygen поощряет возню типа документирования аргументов и возвращаемых значений вместо действительно важных вещей, а в результате получается простыня воды оформленная в стиле интернета 90-х

Неистово плюсую. Синтаксически отдельное описание параметров в doxygen в виде их пересечения - полное снижение читаемости.

Адекватное описание параметров - формулирование описания функции в свободной форме, в котором в подходящих местах эти параметры упоминаются, в том порядке в котором они ложатся на свободную форму этого описания

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

Когда вникаешь в чужой проект, то конечно нужны определения функций, хедеров, …, и конечно исходный код.
Но одними заголовками функций сыт не будешь.
Чисто субъективно мне Doxygen для этого не подходит.
Просто в IDE открываю проект и нужные хедеры, а доступ текстам функций при необходимости тривиален.

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

Нет, не можем - никакого особого опыта у нас нет потому что в IT опыт старее 5 лет вообще не актуален. А видение отличается только тем что мы росли на дерьме из прошлого века, по сравнению с которым самый убогий современный «велосипед» кажется (а на самом деле является) удобнейшим инструментом.

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

Синтаксически отдельное описание параметров в doxygen в виде их пересечения - полное снижение читаемости.

А это сейчас о чем вообще?

формулирование описания функции в свободной форме, в котором в подходящих местах эти параметры упоминаются, в том порядке в котором они ложатся на свободную форму этого описания

По типу такого?

/// Получение значения попадающего в заданный диапазон.
///
/// @return @a value если @a value попадает в дапазон [@a min, @a max],
/// либо @a min, если @a value меньше @a min,
/// либо @a max, если @a value больше @a max.
[[nodiscard]] int
get_value_in_range(int value, int min, int max) {...}

Нет, не можем - никакого особого опыта у нас нет потому что в IT опыт старее 5 лет вообще не актуален.

Это если таковые за хайпом гонятся и считают, что таковой много лучше иных проектов.
Старая песня …

В конечном счёте нужен ведь результат, а не растопыривание пальцев.
Здесь конечно то же мера должна быть и нужно уметь отличить хайп от полезного API.

А это сейчас о чем вообще?

struct Color {
    ////////////////////////////////////////////////////////////
    /// \brief Construct the color from given red, green, blue components
    ///
    /// \param[in] r Red component
    /// \param[in] g Green component
    /// \param[in] b Blue component
    ///
    ////////////////////////////////////////////////////////////
    Color(Uint8 r, Uint8 g, Uint8 b);
}

По типу такого?

Это плохой пример. И тут, и в моём примере, не нужно упоминать аргументы вообще. Тут, правда, нужно ещё нормально назвать функцию.

impl Color {
    /// Construct then color from components
    pub fn new(red: u8, green: u8, blue: u8) -> Self;
}

/// Clamp value to a given range
pub fn clamp(value: u64, min: u64, max: u64);

Я даже навскидку не могу придумать пример где действительно потребуется упоминать аргументы.

Markdown. Использую идиотину для добавления оформительских красот и структурирования.

Есть еще Slite, но после Confluence им пользовать неудобно, потому кладу md’шки прямо в репы.

На работе везде конфлюенс, а в личных проектах ограничивался README.md + комментарии к сложным местам в коде.

Синтаксически отдельное описание параметров - это когда параметры описывабтся последовательно, независимыми фразами (скопировано из «учебника», ибо в коде такой фигни нет)

/*!
Копирует содержимое из исходной области памяти в целевую область память
\param[out] dest Целевая область памяти
\param[in] src Исходная область памяти
\param[in] n Количество байтов, которые необходимо скопировать
*/
void memcpy(void *dest, const void *src, size_t n);

Одна из болей как раз в том что статьи по которым люди знакомятся с doxygen показыают именно этот бестолково-многословный стиль. Как если бы статьи по C++ топили за auto_ptr

Ваш пример где только brief-часть и @return выглядит приемлемо на мой вкус по плотности информации. Чуть раздутости/дублирования смысла всё ж есть, но сходу как это сократить в один brief сохранив понятность я не знаю.

Это пустые слова. Можно гнаться за хайпом, можно сидеть на древнем говне, а можно - взять современный инструмент и сделать.

Нет, не можем - никакого особого опыта у нас нет потому что в IT опыт старее 5 лет вообще не актуален.

Я правильно понял вас, что например Си это старое …?

https://ru.wikipedia.org/wiki/Хронология_языков_программирования

Программировать надо на языках Carbon, Mojo, Gleam и Bend

Программировать надо на языках Carbon, Mojo, Gleam и Bend

Пошучу

В таком случае все популярные проекты это …, так как в основном они используют Си …

Добавочка

… и Linux.

В целом ваша оценка соответствует позиции министерства обороны США.

В целом ваша оценка соответствует позиции министерства обороны США.

Речь совсем не о том была, что кроме Си другие ЯП не следует использовать …

Просто анонимус всё охаял.
Зря с ним и в полемику вступил.

MD, на gitbook, пишу Клодом.

Обычно в Confluence, бывает в Pull Request прямо. Изредка md доки закидываю в docs/ с картинками, схемами.

У себя для пет-проекта в качестве теста использую NOWEB. Сделал отдельные цели у Makefile-а: doc и src. Документацию отправляю в html c кастомным css и небольшими добавками:

$(WEAVE) -filter l2h -index -html timer.nw | \
                 sed "s/<\\/head>/<link rel=\"stylesheet\" href=\"nw.css\"><\\/head>/"  > ./doc/timer.html    

Одна из болей как раз в том что статьи по которым люди знакомятся с doxygen показыают именно этот бестолково-многословный стиль. Как если бы статьи по C++ топили за auto_ptr

Для меня большим преимуществом doxygen после того как довелось поработать с JavaDoc стало то, что в doxygen можно описывать параметры вот так:

/*!
Копирует содержимое из исходной области памяти в целевую область память
*/
void memcpy(
  /// Целевая область памяти
  void *dest,
  /// Исходная область памяти
  const void *src,
  /// Количество байтов, которые необходимо скопировать
  size_t n);

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

Я руководство пользователя к DoubleContact целиком в маркдауне написал, доволен. Но в этом руководстве нет таблиц. :)

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

В слове «пишите» ударение падает на второе «и», потому что это повелительное наклонение.

В каком формате вы пишете документацию к своим проектам?

Просто анонимус всё охаял. Зря с ним и в полемику вступил.

Ностальжи «о старом и никудышнем».

Когда появилась 1С 7.7, то «спец» утверждал - «У тебя всё старое, а вот на 1С» и глаза закатывал.
Так на 1С 7.7 и ныне четыре СЛОЖНЫХ отчёта за пол дня не сделаешь.
У меня это была реальность и всё было крайне просто.
Нужно всего лишь компьютер научить и всё будет ok!
Кстати была такая фича.
На вход даём чеё-то отчёт в виде текста и после анализа был готовый шаблон отчёта, учтывающий правильную сортировку данных, заголовки к детальным строкам, формирование, вложенных итогов, ,,,

Конечно это было …
Хайп много лучше.

Хайп это тренд нынешего времени.
Всунем лохам «передовую технологию»!

Но такого рода комментарии замусоривают код, нет?

Странно, что никто не упомянул Sphinx – проверенное временем решение, которое используется в Ядре и ещё дофига где.

Но такого рода комментарии замусоривают код, нет?

ИМХО, при разработке софта (особенно если код живет десятилетиями), никогда не бывает много:

• проверок на валидность данных;
• логов;
• комментариев.

Все это сугубо субъективное сугубо ИМХО.

По типу такого?

/// Получение значения попадающего в заданный диапазон.
///
/// @return @a value если @a value попадает в дапазон [@a min, @a max],
/// либо @a min, если @a value меньше @a min,
/// либо @a max, если @a value больше @a max.
[[nodiscard]] int
get_value_in_range(int value, int min, int max) {...}

И смысл на текущий момент. Большинство сидит через clangd как Language Server. А эта зараза всё испоганит.

Тогда уж:

/// Получение значения попадающего в заданный диапазон.
///
/// Возвращает `value` если `value` попадает в диапазон `[min, max]`,
/// либо `min`, если `value` меньше `min`,
/// либо `max`, если `value` больше `max`.
[[nodiscard]] int get_value_in_range2(int value, int min, int max);

Это хоть как-то смотрится. И в vim и vscode.

Но вот:

/// Получение значения попадающего в заданный диапазон.
///
/// @return @a value если @a value попадает в диапазон [@a min, @a max],
/// либо @a min, если @a value меньше @a min,
/// либо @a max, если @a value больше @a max.
///
/// @code{.cpp}
/// v = get_value_in_range2(v, 0, 10);
/// @endcode
[[nodiscard]] int get_value_in_range(int value, int min, int max);

/// Получение значения попадающего в заданный диапазон.
///
/// Возвращает `value` если `value` попадает в диапазон `[min, max]`,
/// либо `min`, если `value` меньше `min`,
/// либо `max`, если `value` больше `max`.
///
/// ```.cpp
///     v = get_value_in_range2(v, 0, 10);
/// ``` 
[[nodiscard]] int get_value_in_range2(int value, int min, int max);

Уже плывёт…

Тут правда в clangd-22 обещают хоть какую-то поддержку https://clangd.llvm.org/config#documentation

И будут в проектах появляться .clangd:

Documentation:
  CommentFormat: Markdown

Или для старых проектов:

Documentation:
  CommentFormat: Doxygen

З.Ы.: Так или иначе эти комментарии более полезны в IDE, чем через какой-либо генератор документации.

Большинство сидит через clangd как Language Server. А эта зараза всё испоганит.

Мне пох, я не сижу в clangd.

Так или иначе эти комментарии более полезны в IDE, чем через какой-либо генератор документации.

На IDE мне еще больше пох, ибо не пользуюсь. А вот без сгенерированной doxygen-ом документации крайне неудобно.

Мне пох,

Ну и сиди без нормального автодополнения, автоинклудов, подсветки косяков и т.д. и т.п.

А вот без сгенерированной doxygen-ом документации крайне неудобно.

А я не вижу смысла переключаться из nvim-а ради описания функции.

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

Ну и сиди без нормального автодополнения, автоинклудов, подсветки косяков и т.д. и т.п.

Ну и сижу.

А я не вижу смысла переключаться из nvim-а ради описания функции.

Подобная документация нужна еще до того как хоть что-то будет написано. Вот давеча пришлось знакомиться с taskflow. Так сперва проштудировал сгенерированную для нее документацию (похоже что Doxygen-ом), прежде чем вообще было принято решение использовать taskflow.

Markdown. Хорошо читается и пишется ЛЛМ, да и человеками без специнструментов. Вываливаешь low effort дамп сознания по проекту в общем, просишь ЛЛМ из него сделать что-то приличное, плюс сделать документацию по коду, потом все это правишь и несколько недель гуляешь, а начальству в это время говоришь, что документация будет просто супер)

Но такого рода комментарии замусоривают код, нет?

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