Как задокументировать свойство, объявленное в другом файле, с помощью Doxygen?
Я использую mogenerator для генерации классов CoreData. Mogenerator выпускает классы машин и людей. Разработчик не должен изменять сгенерированные компьютером классы, так как они генерируются каждый раз, когда вызывается mogenerator. Человеческие классы, однако, могут быть изменены по усмотрению разработчика.
Машинные классы содержат объявление каждого свойства объекта CoreData. В Doxygen, как один документ документирует свойство, определенное в файле A, из файла B?
РЕДАКТИРОВАТЬ: Добавлен пример, чтобы проиллюстрировать вопрос
Пример:
В конечном итоге цель здесь иметь нечто похожее на пример ниже.
FileA.h (не может быть изменено)
@interface FileA : NSObject
{
NSString* myProperty;
}
@end
FileB.h
#include "FileA.h"
@interface FileB : FileA
{
/**
* @property myProperty
*
* This is the documentation of "myProperty"
* defined in FileA but documented in FileB
*/
}
@end
Пробовал (блок документации внутри @interface FileB @end bock):
@property myProperty - Doxygen не связывает документацию со свойством.
\ property myProperty - Doxygen не привязывает документацию к свойству.
@property FileA:: myProperty - Doxygen не связывает документацию со свойством и генерирует; предупреждение: не найден однозначно совпадающий член класса для FileB:: myProperty
\ property FileA:: myProperty - То же самое
Решение
FileB.h
#include "FileA.h"
/**
* @property FileA::myProperty
*
* This is the documentation of "myProperty"
* defined in FileA but documented in FileB
*
* Documentation block MUST BE outside FileB class
*
*/
@interface FileB : FileA
{
}
@end
2 ответа
Неясно (для меня) хотите ли вы FileA
документироваться, но вы не можете вставить документацию в FileA.h
или, если хотите FileA
быть недокументированным, но иметь его членов в (документированном) производном классе FileB
,
Если это первое, вы можете предоставить документацию для класса FileA
в FileB.h
это будет выглядеть примерно так:
/**
* @class FileA
* Documentation for FileA
*
* @var FileA::myProperty
* Documentation for myProperty
*/
/**
* Documentation for FileB
*/
@interface FileB : FileA
{
}
@end
Это приведет к занятиям FileA
а также FileB
появляться в сгенерированных документах, с myProperty
зарегистрирован как член FileA
,
Если это последнее, вы могли бы объявить myProperty
как член FileB
, но используйте защиту препроцессора, чтобы включить объявление только при генерации вашей документации, что-то вроде:
/**
* document FileB
*/
@interface FileB : FileA
{
#ifdef DOXYGEN
/**
* This is the documentation of "myProperty"
* defined in FileA but documented in FileB
*/
NSString* myProperty;
#endif
}
@end
Это приведет к FileB
документироваться как myProperty
был одним из его членов. Имейте в виду, что если декларация myProperty
изменения в FileA
, вам придется вручную обновить FileB
декларация, чтобы отразить эти изменения.
Вы можете ссылаться на ахор (например, файлы, пространства имен, классы, функции, переменные, перечисления и т. Д.), Используя Doxygen's ref
команда с использованием, например,
\ref variable_name
Если переменная, которую вы хотите задокументировать, не находится в локальном пространстве имен или области, вы можете добавить к имени переменной префикс namespace::
, где namespace
это область или класс, в котором определяется переменная, на которую вы ссылаетесь. Например, рассмотрим следующие два файла (модифицированные из примеров в руководстве по Doxygen):
Файл 1:
/// A test class.
/**
A more elaborate class description.
*/
class Test
{
public:
/// An enum.
/** More detailed enum description. */
enum TEnum {
TVal1, ///< Enum value TVal1.
TVal2, ///< Enum value TVal2.
TVal3 ///< Enum value TVal3.
}
/// Enum pointer.
/** Details. */
*enumPtr,
/// Enum variable.
/** Details. */
enumVar;
/// A constructor.
/**
A more elaborate description of the constructor.
*/
Test();
};
Файл 2:
// Another test class.
/**
This class depends on the variable \ref Test::TEnum, defined in another file.
It doesn't, actually, but I've said it does.
*/
class AnotherTest
{
public:
/// A constructor
AnotherTest();
};
Вот TEnum
определяется в классе Test
в первом файле. Таким образом, во втором файле мы добавляем префикс имени переменной к классу, в котором она определена, т.е. Test::TEnum
,
См. Принятый ответ на вопрос. Ссылки на статические переменные const, объявленные в пространстве имен, для получения дополнительной информации о префиксе глобального пространства имен. ::
,