Doxygen for property declared in a different file using?

Question

I use mogenerator to generate Core Data classes. Mogenerator produces machine classes and human classes. A developer is not supposed to modify machine generated classes, since these are generated each time mogenerator is called. Human classes can, however, be modified as the developer pleases.

Machine classes contain the declaration of every property of the Core Data entity. In Doxygen, how does one document a property defined in file A from file B?

EDIT: Added example to illustrate the question

Example:

Ultimately, the goal here to have something similar to the example below.

FileA.h (can not be modified)

@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

Tried (documentation block inside the @interface FileB @end bock):

@property myProperty - Doxygen does not associated the documentation to the property.

\property myProperty - Doxygen does not associated the documentation to the property.

@property FileA::myProperty - Doxygen does not associated the documentation to the property and generates; warning: no uniquely matching class member found for FileB::myProperty

\property FileA::myProperty - Idem

Solution

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

Answer 1

Its unclear (to me) whether you want FileA to be documented, but you can't insert the documentation into FileA.h, or if you want FileA to be undocumented, but have its members appear in the (documented) derived class FileB.

If its the former, you can provide documentation for class FileA in FileB.h, this would appear as something like:

/**
 * @class FileA
 * Documentation for FileA
 *
 * @var FileA::myProperty
 * Documentation for myProperty
 */

/**
 * Documentation for FileB
 */
@interface FileB : FileA
{
}

@end

This will cause classes FileA and FileB to appear in the generated docs, with myProperty documented as a member of FileA.

If its the latter, you could declare myProperty as a member of FileB, but use a preprocessor guard to only include the declaration when generating your documentation, something like:

/**
 * document FileB
 */
@interface FileB : FileA
{
#ifdef DOXYGEN
    /**
     * This is the documentation of "myProperty" 
     * defined in FileA but documented in FileB
     */
    NSString* myProperty;
#endif
}

@end

This will cause FileB to be documented as if myProperty was one of its members. Be aware that if the declaration of myProperty changes in FileA, you'll have to manually update FileB's declaration to reflect those changes.

Answer 2

You can reference an achor (e.g. files, namespaces, classes, functions, variables, enums etc) using Doxygen's ref command using, for example

\ref variable_name

If the variable you want to document is not in the local namespace or scope, you can prefix the variable name with namespace::, where namespace is the scope or class where the variable you are referring to is defined. For example, consider the following two files (modified from examples in the Doxygen manual):

File 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();
};

File 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();

};

Here TEnum is defined in the class Test in the first file. So in the second file, we prefix the variable name with the class in which it is defined, i.e. Test::TEnum.

See the accepted answer to the question Reference static const variables declared in namespace for more information on the global namespace prefix ::.