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

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

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

Да ладно, это же интересно

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

/* копирует n байт из src в dest */
void memcpy(void *dest, const void *src, size_t n);

Мне нет. Мне проще самому с нуля написать так, как я хочу, чем потом за неёронками причёсывать весь выхлоп.

Для людей с выраженной альтернативной одаренностью вынужден заметить, что:

• это не мой пример вообще;
• смысл модифицированного мной примера в том, чтобы показать, в каком месте еще Doxygen позволяет оставлять документацию к параметрам функции/метода (есть ощущение, что кто-то даже не в курсе, что Doxygen так умеет).

Pdf и odt. Писать приходится со схемами

Мне проще самому с нуля написать так, как я хочу, чем потом за неёронками причёсывать весь выхлоп.

Понимаю) Но все равно, если запаришься с какими-то частями, у тебя есть опция спихнуть это ЛЛМ. Они в общем-то, что им скажешь, то и будут делать.

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

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

Обычно - ни в каком. Мне лень и всё равно кроме меня её никто читать не будет. А я и так всё знаю. Если и забуду, то быстрей разобраться по коду, чем читать потенциально устаревший текст.

Но если и пишу, то, конечно, в markdown. Даже странно рассматривать что-либо ещё.

У меня прям больших проектов нет. Есть работа, есть разные поделки, но в основном так:

1. На работе просто пишу в README.md, плюс, страничка на рабочей вики.

2. Просто текстовый файл в стиле, который у OpenBSD подсмотрел. textwidth = 72, а заголовки следующим образом:

This is a title example
-----------------------

Regular paragraph. This command will fix your computer:

        rm -rf /*

3. Создаю отдельную директорию doc/ и в ней пишу документацию в разметке markdown, но также она собирается в pdf с помощью pandoc. А также добавляю LaTeX преамбулу. Иногда прям в markdown разметку добавляю LaTeX-команды.

4. В начале программы в комментарии описать, а что собственно программа делает и какие подпрограммы ключевые.

Rd, Texinfo.

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

Требования к ним разные. API-документация должна быть мгновенно доступна при работе с кодом; её формат сильно зависит от языка и фреймворков (например, встроенная в R система справки понимает только Rd, хотя есть и трансляторы из других языков в него). Инструкции, которые учат читателя делать конкретные вещи, лучше писать в духе literate programming, чтобы было легко убедиться, что предложенный код действительно работает (опять же, конкретные инструменты зависят от языка и других обстоятельств). А вот документ для вдумчивого чтения можно писать на чём удобно (в том числе что потом будет удобно читать через браузер или даже электронную книгу).

Для high level документации, общей архитектуре, спецификаций и всему далёкому от кода использую mdBook.

Для API reference, описания конкретных классов (контракты и интерфейсы), coding guidelines и всему связанному с кодом — Doxygen с Doxygen Awesome CSS.

Нет, твой - ты его сюда принёс и снабдил положительным отзывом. Где ты его достал плевать.

чтобы показать, в каком месте еще Doxygen позволяет оставлять документацию к параметрам функции/метода (есть ощущение, что кто-то даже не в курсе, что Doxygen так умеет).

Да и пусть не в курсе, незачем знать способы испортить код.

goingUp ★★★★★ (13.11.25 17:01:04 MSK) злостный адепт ии-мусора

незачем знать способы испортить код

Наоборот их надо знать для того, чтоб не портить код ;)

doxygen, Latex, readme.md - для себя и подобных, draw.io - диаграмочки для понимания начальством.

Тут вообще комментарии излишни, достаточно самодокументации в коде:

void copyNumBytes(void *to, const void *from, size_t numBytes);

Комментарии нужны, когда алгоритм нетривиальный и надо сделать пометку «ты сюда не ходи - сюда ходи, а то снег башка попадёт!».

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

По-моему такие функции комментировать - только портить, по мне дак пример самодокументированного кода

Нет, твой

Для клинических идиотов первоисточник: В каком формате вы пишете документацию к своим проектам? (комментарий)

Да и пусть не в курсе, незачем знать способы испортить код.

Я понимаю, что альтернативная одаренность не позволяет различить два ортогональных друг другу вопроса:

1. Нужно ли описывать параметры функции/метода?
2. Как именно можно описывать параметры функции/метода посредством Doxygen?

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

Для клинических идиотов первоисточник

Клинический идиот тут ты. По ссылке совсем другое, никаких мусорных комментариев после каждого аргумента там нет, комментировал я не его а именно твой пример. У него нет «10 строк нечитаемой каши», которые представляет из себя твой вариант. У него нормальная 1 строка кода и раздутый 6-строчный коммент.

Как именно можно описывать параметры функции/метода посредством Doxygen?

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

Однако вы, почему-то, пытаетесь приписать мне ответ на первый вопрос.

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

Смотря какую документацию. PRD обычно выкатывают просто в гуглдоксах. HLD/LLD пишу изначально в org+plantUML. Потом конвертирую куда надо. Вообще важнее чтобы была платформа для коллаборации (вопросы, правки, интеграция со слаком, таск/баг-трекером и т.д.), а не просто документ.

Клинический идиот тут ты.

А я и не отрицаю. Меня больше другое волнует: что в этой теме слишком большая концентрация еще более запущенных случаев.

По ссылке совсем другое

понимать надо (с)

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

Все.

Способ, который ты показал в своём примере - отвратителен

Если он вам не нравится, то не пользуйтесь. Doxygen как раз хорош тем, что не навязывает какое-то один подход.

преподносить его в качестве «а вот какая крутая фича у doxygen» - идиотизм

По факту, у Doxygen-а это реально крутая штука. Говорю вам как человек, которому по работе пришлось заниматься приведением в норму JavaDoc комментариев, в которых по мере развития проекта описания параметров забывали редактировать. Именно потому, что комментарии к параметрам шли отдельно, а сами параметры – отдельно.

Это антифича, единственное зачем это можно было показать - так это в контексте «смотрите, как не надо делать».

У меня к вам внезапный, но традиционный для моего поведения на LOR-е вопрос: а ваш код где-то в открытом доступе увидеть можно?

приведением в норму JavaDoc комментариев, в которых по мере развития проекта описания параметров забывали редактировать. Именно потому, что комментарии к параметрам шли отдельно, а сами параметры – отдельно.

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

У меня к вам внезапный, но традиционный для моего поведения на LOR-е вопрос: а ваш код где-то в открытом доступе увидеть можно?

Например тут и тут и тут (про просроченный сертификат знаю).

markdown, vim, pandoc.

Например

Прикольно слушать категорическое мнение о нужности комментариев от человека, творящего вот такое:

/* ret. 0 = ok; -1 = too many headers; -2 = too long header name; -3 = bad header name; -4 = too long header value; -5 = missing ':' */
extern int hh_add(t_http_headers * hh, char const * text) {
  int r;
  unsigned int n;
  char *hname, *hvalue;
  
  if(hh->n>MAX_HEADERS) abort();
  if(hh->n==MAX_HEADERS) return -1;
  r = hh_parse(text, &hname, &hvalue);
  if(r<0) return r;
  n = hh->n++;
  hh->h[n*2] = hname;
  hh->h[n*2+1] = hvalue;
  return 0;
}

/* ret. 0 = ok; -2 = too long header name; -3 = bad header name; -4 = too long header value; -5 = missing ':' */
extern int hh_parse(char const * text, char * * r_name, char * * r_value) {
  unsigned int n, ow;
  char c;
  char name[MAX_HEADER_NAME];
  char *hname, *hvalue;
  size_t vlen;
  
  while(*text==' ' || *text=='\t') text++;
  for(n=0; n<MAX_HEADER_NAME; n++) {
    c = text[n];
    if(!c) return -5;
    if(c==':') break;
    name[n] = c;
  }
  if(n==MAX_HEADER_NAME) return -2;
  text += n+1;
  while(n && (name[n-1]==' ' || name[n-1]=='\t')) n--;
  name[n] = 0;
  if(!n) return -3;
  for(n=ow=0; c=name[n]; n++) {
    if(c=='_' || c=='-') { name[n]='-'; ow=0; continue; }
    if(c>='A' && c<='Z') { if(ow) name[n]=c-'A'+'a'; ow=1; continue; }
    if(c>='a' && c<='z') { if(!ow) name[n]=c-'a'+'A'; ow=1; continue; }
    if(c>='0' && c<='9') { ow=1; continue; }
    return -3;
  }
  while(*text==' ' || *text=='\t') text++;
  if(strlen(text)>=MAX_HEADER_VALUE) return -4;
  hname = fcl_strdup_check(name);
  hvalue = fcl_strdup_check(text);
  vlen = strlen(hvalue);
  while(vlen && (hvalue[vlen-1]==' ' || hvalue[vlen-1]=='\t')) hvalue[--vlen] = 0;
  *r_name = hname;
  *r_value = hvalue;
  return 0;
}

Видимо, есть сильная обратная корреляция между качеством кода и категоричностью мнения.

Org mode. Для бедных есть экспорт в другие форматы.

Этот вполне хороший код, не надо левых наездов. И комментарий полезный, в отличие от «src это исходная память». И упрощу тебе поиски: как раз в fproxy, единственном из тех трёх ссылок, плохой код есть, но он в основном в файлах handle/inc.*.c

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

Комментарии в коде проще всего поддерживать. Отдельные документы в txt или markdown. Если нужно прям сайт сгенерировать, когда-то давно использовал rst. Собственно можно прям цепочку выстроить каменты/txt < markdown < rst по нарастанию сложности формата и его возможностей.

начать писать полноценную

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

Только массовые расстрелы, только хардкор