Почему в заголовках комментариев в C или C++ есть избыточные косые черты "*//**"
Я часто вижу:
/**************************************************************************//**
* some comments
*****************************************************************************/
Почему нет:
/*****************************************************************************
* some comments
*****************************************************************************/
Насколько я понимаю, для обработки doxygen требуются специальные комментарии (см.: Документирование кода). Но у него также есть возможность включить JAVADOC_BLOCK в doxyfile. Зачем жертвовать эстетикой кода, если в этом нет необходимости? Вы также можете добавить команды doxygen в эти блоки или оставить их, если хотите.
Редактировать: Я получаю неожиданное поведение при проверке JAVADOC_BLOCK, но при снятии флажка JAVADOC_AUTOBRIEF. Это все еще автобрифинг.
Если для тега JAVADOC_AUTOBRIEF установлено значение YES, doxygen интерпретирует первая строка (до первой точки) комментария в стиле Javadoc в качестве краткого описания описание. Если установлено значение NO, стиль Javadoc будет вести себя так же, как обычный Qt-стиль. комментарии к стилю (таким образом, для краткого описания требуется явная команда @brief). описание.) [выделено мной]
/******************************************************************************
*
* \file a.c
*
******************************************************************************/
/******************************************************************************
*
* javadoc header without brief
*
******************************************************************************/
void a(void)
{
}
/******************************************************************************
*
* \brief javadoc header with brief
*
******************************************************************************/
void b(void)
{
}
/**************************************************************************//**
*
* doxystyle header without brief
*
******************************************************************************/
void c(void)
{
}
/**************************************************************************//**
*
* \brief doxystyle header with brief
*
******************************************************************************/
void d(void)
{
}
int main(void)
{
a();
b();
c();
d();
return 0;
}
В doxygen-1.11.0 a и c автобриф
Редактировать2: Я думаю, doxygen нельзя настроить так, как я хочу. Я вынужден использовать их эстетически неприятный стиль комментариев. Лучшее улучшение, которое я мог бы сделать, — это использовать это (обратите внимание, что звездочки в конце теперь выровнены):
/*************************************************************************//**
* some comments
*****************************************************************************/
Ответ прост: разработчики либо не знают о настройке, либо не удосужились ее установить.
Еще лучше: оставьте пустую трату времени комментарии «🤩🤩🤩🤩🤩 Боже мой! Здесь полно звезд! 🤩🤩🤩🤩🤩» и используйте простую строку /**, чтобы начать документацию Doxygen или Javadoc.
Разработчик может захотеть использовать какие-нибудь причудливые блоки комментариев, которые будут игнорироваться Doxygen при установке JAVADOC_BANNER = NO.
Можно также задать вопрос: зачем мне копаться в опциях Doxygen, если я могу просто заменить две звездочки двумя косыми чертами? :) («Эстетика кода» выходит на субъективную территорию. Не все вынуждены соглашаться с вашей оценкой..)
@JaMiT Я согласен, что эстетика может быть субъективной. Но в этом случае он объективно менее чистый/последовательный и нарушает соглашение. Лично мне не нравятся заголовки Christmaslights, но если я их использую, то хочу, чтобы они были чистыми. Это еще и удобство. Изменение стиля комментариев, чтобы инструмент видел их, когда они не нужны.
@elechris «Но в данном случае он объективно менее чистый/последовательный» — в тривиальной степени, которую легко игнорировать, поэтому для кого-то проблема может быть незначительной — «и нарушает соглашение» — нет, если ваше соглашение предполагает использование этого стиль. Это все еще субъективный звонок.
Ответы 2
Документация Doxygen , на которую вы ссылаетесь , на самом деле содержит ответ (показывающий именно тот стиль, который вы упомянули):
- Некоторым людям нравится делать свои блоки комментариев более заметными в документации. Для этой цели вы можете использовать следующее:
/********************************************//** * ... text ***********************************************/Примечание: две косые черты завершают обычный блок комментариев и начинают специальный блок комментариев.
Примечание. Будьте осторожны при использовании преобразователя, такого как clang-format, так как это может рассматривайте этот тип комментариев как два отдельных комментария и вводите пробелы между ними.
(выделено мной)
Итак, чтобы ответить на ваш вопрос, на самом деле в этом нет необходимости, но некоторые люди используют его, чтобы сделать свои блоки комментариев более заметными в документации.
Обновлять:
Оказалось, что документация Doxygen, приведенная выше, на самом деле не дает хорошего объяснения двум косым чертам. Они добавляются, чтобы превратить комментарий в комментарий Doxygen, но есть лучший способ сделать это:
Добавьте флаг JAVADOC_BANNER, и тогда вы сможете использовать следующую более чистую версию (без косых черт), которая не менее заметна:
/************************************************
* ... text
***********************************************/
Это означает, что ответ на ваш вопрос указан в комментарии @HolyBlackCat выше:
Причина странного стиля с двумя косыми чертами в том, что разработчики либо не знают об этой настройке, либо не удосужились ее установить.
косые черты не делают его более заметным, поэтому он не отвечает на мой вопрос
«Чтобы сделать движение видимым» — это ответ на вопрос «почему куча *, а не ничего». Пока ОП спрашивает что-то еще, они спрашивают: «Почему ****//** вместо *****, если вы можете заставить последнее работать, включив настройку doxygen».
@HolyBlackCat в документации doxygen приведен именно этот пример, включая две косые черты в конце, как пример того, как сделать комментарий более заметным. В примечании даже упоминаются две косые черты. Пожалуйста, смотрите ссылку на документацию. Что я пропустил ?
В документации не сказано, что // делает комментарий более заметным. Куча * делает его более заметным. // в конце просто превращает его в действительный комментарий doxygen. Вопрос в том, зачем использовать эти //, если вы также можете разрешить эти комментарии с помощью флага doxygen.
@HolyBlackCat Я наконец-то понял твою точку зрения. Я не эксперт по doxygen и поэтому изначально пропустил это. Я думаю, что документация doxygen немного сбивает с толку по этому вопросу. Я добавил обновление к ответу.
«но некоторые люди используют его, чтобы сделать свои блоки комментариев более заметными в документации». -- Не совсем. Некоторые люди используют его либо 1) для того, чтобы сделать источник документации более видимым в коде, либо 2) чтобы сделать хорошо заметный комментарий выполняющим двойную функцию в качестве источника документации, сгенерированной Doxygen. Зависит от вашей точки зрения. В любом случае, видимость в документации не пострадает. (На самом деле, весь смысл этого трюка в том, чтобы заставить Doxygen пропустить большую часть первого ряда звездочек.)
Иногда хочется поместить в исходный код большой комментарий-разделитель, просто чтобы разбить исходный код.
Например, если у вас есть набор связанных структур (или классов C++) в одном заголовочном файле (поскольку вам нравятся большие заголовочные файлы), вы можете рассмотреть возможность вставки большого комментария к баннеру, сообщающего читателю, что «Это основной класс». , или «это все внутренние структуры». Помните, что в c у вас нет такой гибкости, позволяющей скрывать служебные структуры внутри объектов, которые их используют.
Вы просто не хотите, чтобы этот комментарий попал в сгенерированный файл документации, если он ничего не добавит к документации.
В других случаях вам нужен большой стиль баннера в файле, но затем вы решаете, что вам действительно нужен контент в сгенерированном файле документации, потому что он добавляет некоторую ценность. Иногда это позднее редакционное решение.
Конечно, вы также можете использовать теги Javadoc для создания разделов в документации, которые вы можете использовать для сопоставления связанных внутренних структур, и вы можете использовать для этого существующие баннеры - или нет, это выбор, иногда возникающий из-за нежелания. чрезмерно усложнять создаваемую документацию.
Трюк /***************************// позволяет вам индивидуально включать некоторые баннеры в документацию, игнорируя при этом большинство из них и не слишком сильно переформатировать исходный файл.
«Вы просто не хотите, чтобы этот комментарий попал в сгенерированный файл документации, если он ничего не добавит к документации». Я только что протестировал его и обнаружил, что даже если я сниму флажок с JAVADOC_AUTOBRIEF, он все равно будет автоматически информировать Javadoc, если я проверю JAVADOC_BANNER. Вы думаете, что есть способ не выполнять автоматический брифинг Javadoc? Я обновил свой вопрос примером. Потому что если есть способ не проводить автобрифинг, то я не вижу в этом проблемы.
Итак, у вас есть случай 1:
/** some comment .... По моему мнению, ваша вторая часть часто используется в коде, например. лицензии, авторские права, но и в других местах), которые не должны были быть частями doxygen. Просто важное наследие. Но только догадываюсь