Соглашения Doxygen C ++
Я в начале проекта C ++, и я использовал Doxygen с самого начала.
Я хотел бы знать, как вы используете Doxygen в своем проекте, т.е. у меня есть несколько вопросов:
1. Где вы размещаете ваши комментарии Doxygen? Заголовок или источники?
Я думаю, что они должны идти в заголовок, потому что именно там я смотрю, чтобы узнать, как использовать методы. Тем не менее, я хотел бы опустить фактические имена параметров в прототипах, поэтому я не могу использовать @param - или я могу? Как вы справляетесь с этим?
2. Документируете ли вы все методы?
Пока я документирую только публичные методы, как вы это делаете? Документируете ли вы методы доступа и публичные переменные?
3. Всегда ли вы заполняете @param и @return?
Где я работаю (это Javadoc, но это та же проблема), у нас есть соглашение, чтобы заполнять только действительно необходимые свойства, т.е. если в кратких описаниях написано «Возвращает xys if. .. ", мы опускаем @return. Если имена параметров очевидны, мы их опускаем. Я до сих пор не уверен, нравится ли мне такой подход, как ты это делаешь? Пока что я заполнил только краткое изложение и ничего более, но не все прототипы методов достаточно просты для этого.
4. Какой стиль вы используете?
В Doxygen есть несколько стилей: Javadoc (/ ** ... /), QT (/ ! ... */) и более. Чисто из интереса: какой из них вы используете? Я еду с банкоматом в стиле Javadoc, потому что привык к нему.
2 ответа
1. Куда вы помещаете свои комментарии Doxygen? Заголовок или исходники?
Я не могу ответить на этот вопрос, потому что на самом деле я не помню, где я обычно документирую с точки зрения заголовка или исходников.
2. Документируете ли вы все методы?
Почти полностью да. Каждый метод документируется в той или иной форме, если только из имени переменной/метода (и имен параметров для методов) не становится ясно, что конкретно он делает. Я склонен придерживаться правила: "Если вы не можете понять назначение метода по его названию и именам параметров, его нужно прокомментировать. Если после комментария вы все еще не можете понять назначение метода, перепишите комментарий. Если вы все еще не можете быстро понять назначение метода, или если комментарий "слишком длинный" (где "слишком длинный" - это произвольное измерение >_>), то вам нужно переписать метод или разделить его."
3. Всегда ли вы заполняете @param и @return?
Да. Даже если это ослепительно очевидно из чтения @brief, или если @return является точной копией предложения в @brief, я все равно заполняю их. Может быть очень полезно иметь такое свойство сканирования документации метода. "О, метод X, я знаю, что он делает и зачем, но какое именно значение он возвращает в ситуации X?" *проверяет @return*.
4. Какой стиль вы используете?
Я использую Javadoc, хотя это совершенно субъективно. Я использую синтаксис Javadoc, потому что я некоторое время писал на Java и очень привык к этому синтаксису. Кроме того, я лично думаю, что он имеет больше смысла, чем другие - мне просто совсем не нравится синтаксис QT.
1. Где вы размещаете свои комментарии к Doxygen? Заголовок или источники?
Документация идет в заголовках, поскольку именно здесь определяется интерфейс.
2. Вы документируете все методы?
Для классов я документирую все общедоступные и защищенные методы, я обычно оставляю частные методы в покое.
3. Вы всегда заполняете @param и @return?
Я предпочитаю встроенную документацию по параметрам
/*!
* \brief My great class.
*/
class Foo
{
public:
/*!
* \brief My great method.
*/
void method(
int parameter //!< [in] parameter does something great
);
};
, а не использовать \ param , поскольку это приводит к дублированию имени параметра и легко может рассинхронизироваться с кодом, когда ленивые разработчики забывают изменить doxygen.
\ return опускается, если есть тип возврата void. Я всегда использую \ throw , когда метод может бросать.
4. Какой стиль вы используете?
Не имеет значения, если он соответствует всему проекту.