И сейчас в случае с doxygen это просто файлы Markdown скармливаемые doxygen напрямую. И это в результате может стать не просто отдельной самостоятельной страницей в документации, но в них можно указать какие отрывки текста должны появиться в какой странице или в какой раздел («модуль» в терминах doxygen) добавиться к автоматически сгенерированной документации кода. (К сожалению вот только локализовать место вывода до конкретной функции-члена класса нельзя.)
Так что мешает подключить файлы с абстрактным описанием в документацию doxygen, а обычные комментарии в коде с минимальными усилиями превратить в doxy-комментарии? Бессмысленные аннотации объявлений генерируются doxygen автоматом и это может быть отключено, тогда doxygen выведет только то, что было реально задокументировано.
Но даже если умолчальный доксигеновский HTML и устраивает кого-то с визуальной точки зрения (а серьёзно, есть такие, кому он и вправду нравится эстетически? напишите в комментариях!), очень часто хочется поменять и настроить что-то выходящее за рамки подкручивания CSS — например, упечь объявления в <pre> и расставить отступы и пробелы в соответствии с принятым в данной конкретной библиотеке coding-style.
Дефолтный вывод докигена ужастен (от слов «ужас» и «жесть»). Настолько что когда я первый раз увидел что он сгенерил, то сразу пошел искать возможные альтернативные инструменты. Но не найдя ничего более функционального с точки зрения именно процесса создания и поддержания актуальной документации из исходных файлов (равно как из любых других дополнительных источников документирования проекта), пришлось обратиться к правке HTML_STYLESHEET чтобы привести вывод в более менее приличный вид, и LAYOUT_FILE для того чтобы подкорректировать структуру документации сделав её более понятной, чтобы некоторые дефолтно генерируемые разделы не вводили пользователя в состояние фрустрации.
Это подводит нас ко второй, более фундаментальной проблеме Doxygen...
Проблем у доксигена полно, да. Но по функциональности и возможностям настройки обработки исходников C/C++ для генерации документации он пока не имеет равных. Он может быть и «деревянный» у себя внутри, но в конце концов после изучения и настройки работает и делает то что нужно: генерирует актуальную полноценную документацию из исходников и прочих файлов описания с минимальными трудозатратами на поддержку собственно документирования в исходниках рядом с актуальным кодом.
Да, кстати вот получается __attribute__((packed)) решает проблему, а стандартизированный _Alignas(...) не может выравнять меньше чем на естественную границу.
«Мы» не злые. «Мы» точно такие же как «они» (с поправкой на историческую культуру, процесс общественно воспроизводимого менталитета и индивидуальные: воспитание, опыт и социальные инстинкты).
Почему многим русскоговорящим специалистам в области CS всегда обязательно доказывать окружающим, что окружение полное говно и ничего не понимают в своей области?
Самый простой случай — детская болезнь у новоявленного специалиста, который считает, что понял всё что нужно в некой области, но не способен выразить этот «факт» в иной форме.
Другой вариант — «Я уличил вас в ошибке / недостаточном знании предмета и как следствие глупости» => Некое самоутверждение что я разбираюсь в данной области не хуже чем автор статьи. Некоторые задерживаются в этой стадии достаточно надолго, становясь местными форумными «экспертами», что вполне их устраивает. Но если человек не глуп и занимается реальными задачами, то рано или поздно он перерастает эту стадию: хотя толерантность к вываливающийся с экрана глупости, мнимой или объективной, внутренне может оставаться низкой, его комментарии конечно не становятся позитивными, но становятся более сдержанными и добрыми поскольку потребность в виртуальном самоутверждении постепенно растворяется. Да и вообще, человек, который любит людей, в конце концов придет к мнению, что не стоит сильно злиться из-за людской глупости и несовершенств. :)
Почему наши люди самоутверждаются за счет унижения других? Почему англоговорящие не такие?
Да, на самом деле это так — «ни у кого не хватает смелости расширить список контекстов» и, действительно, «нет никаких физических преград включить копирующие контексты в список исключений». Как хорошо бы иметь возможность просто написать: a = b или a = f(), где a и b — массивы одинаковой статической размерности (не нужно заморачиваться с memcpy() — разве не круто), а функция f() — просто супер — возвращает массив, копируя его поэлементно наружу.
Ни у кого не хватает смелости сделать массивы копируемыми в языке Си, да и соображения обратной совместимости, понятное дело, мешают сильно. :(
Причина в том, что для того, чтобы всего лишь из имени массива можно было волшебным образом получать информацию о его размерности (чтобы иметь возможность использовать/передавать/возвращать массив как объект первого класса) необходима ещё служебная структура данных хранящая информацию об этом. Си — это достаточно низкоуровневый язык и типы данных, которые несут с собой такие такие скрытые структуры в нем отсутствуют как класс by design. К «проблеме» «глупой синтаксической оптимизации» это не имеет совершенно никакого отношения.
Не очень понятно — человек взял написал и говорит, что это полезно и приятно.
А у вас как-то не аргументировано.
Пример: линк. Собственно сам веб-сайт doxygen сгенерирован doxygen.
Проблем у доксигена полно, да. Но по функциональности и возможностям настройки обработки исходников C/C++ для генерации документации он пока не имеет равных. Он может быть и «деревянный» у себя внутри, но в конце концов после изучения и настройки работает и делает то что нужно: генерирует актуальную полноценную документацию из исходников и прочих файлов описания с минимальными трудозатратами на поддержку собственно документирования в исходниках рядом с актуальным кодом.
__attribute__((packed))решает проблему, а стандартизированный_Alignas(...)не может выравнять меньше чем на естественную границу.Самый простой случай — детская болезнь у новоявленного специалиста, который считает, что понял всё что нужно в некой области, но не способен выразить этот «факт» в иной форме.
Другой вариант — «Я уличил вас в ошибке / недостаточном знании предмета и как следствие глупости» => Некое самоутверждение что я разбираюсь в данной области не хуже чем автор статьи. Некоторые задерживаются в этой стадии достаточно надолго, становясь местными форумными «экспертами», что вполне их устраивает. Но если человек не глуп и занимается реальными задачами, то рано или поздно он перерастает эту стадию: хотя толерантность к вываливающийся с экрана глупости, мнимой или объективной, внутренне может оставаться низкой, его комментарии конечно не становятся позитивными, но становятся более сдержанными и добрыми поскольку потребность в виртуальном самоутверждении постепенно растворяется. Да и вообще, человек, который любит людей, в конце концов придет к мнению, что не стоит сильно злиться из-за людской глупости и несовершенств. :)
См. первый вопрос.
Ни у кого не хватает смелости сделать массивы копируемыми в языке Си, да и соображения обратной совместимости, понятное дело, мешают сильно. :(
а не сразу
#xe network-param-set uuid=uuid other-config:static-routes=46.4.205.64/29/172.16.1.10