objective-cdocumentationdoxygendocumentation-generationmogenerator

Doxygen for property declared in a different file using?


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

Solution

  • 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.