Doxygen, слишком тяжелый для поддержания? [закрытый]

Что-то серьезно не так с тем, как вы используете комментарии или как вы разрабатываете.

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

Если вы используете doxygen для документирования внутреннего потока функций, вам, возможно, стоит переосмыслить этот подход (и даже тогда эти комментарии не должны сильно меняться). Когда у вас есть функция, которая вычисляет какое-то значение, тогда комментарий /// Расчет xy с использованием алгоритма abc определенно не должен меняться каждый день.

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

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

В моем профессиональном опыте работы с программным обеспечением каждый раз, когда изменяется исходный файл, необходимо вводить комментарий, описывающий изменение. Эти комментарии к изменениям обычно не находятся в областях комментариев Doxygen (если не были внесены изменения в интерфейс).

Я настоятельно рекомендую вам сделать комментирование кода привычкой. Это не только хорошо, когда другим людям приходится поддерживать ваш код или помогать вам с ним, но и помогает, когда вы на какое-то время оставляете исходный файл (например, когда руководство говорит вам переключить проекты). Я обнаружил, что написание комментариев во время написания кода помогает мне лучше понять алгоритмы.

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

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

Советы:

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

Вы будете рады, когда придете отредактировать свой код через 6 месяцев ...

Я считаю, что вы получаете обратно то, что вы вкладываете в комментарии, 5 минут комментирования класса хорошо, через 3 месяца, когда класс должен быть изменен кем-то другим, кроме оригинального автора (действительно, иногда оригинальным автором), потребуется гораздо меньше времени, чтобы разобраться с ним.

Я поддерживаю поддержку документации, упомянутую Дэвидом, в eclipse, когда вы рефакторите имена параметров, он переименует параметр, например, в вашем разделе документации. Я не уверен, что хотел бы, чтобы он делал что-то еще автоматически, если честно.

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

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

///\file

/// Brief description goes here
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but 
     /// @retval 1 will not do so for parameters. (see below)
PLL_start( 
   unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
                           ///     comment will go also. \n
                           /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n
                           /// 2-32767: whatever
   int param)              ///< 0: crash \n
                           ///  1: boom \n
                           ///  2: bang!
{
   /**
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
    * - Explain in list form.
    * - It really helps the maintainer to grok the code faster.
    *
    *@attention Explain misuses which aren't caught at runtime.
    *
    *@pre Context:
    * - This function expects only a small stack ...
    * - The call is either blocking or non-blocking. No access to global data. 
    *
    *@post The Foobar Interrupt is enabled. Used system resources:
    *    - FOO registers 
    *    - BAR interrupts
    */
    /**@post This is another postcondition. */
}

В дополнение к Doxygen, я думаю, вам стоит взглянуть на Code Rocket .

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

Он автоматически предоставит вам блок-схему и псевдокод визуализации содержимого вашего метода в виде документации.