Search code examples
phpdoxygenidiorm

Document dynamic member variables

I document model classes (in PHP) with Doxygen. I am using Idiorm & Paris as an ORM and I would like the dynamic member variables (coming straight from the database) also to appear in the generated documentation.

Example: I have a model Group with some methods like isMember() or users() documented with Doxygen. In the database I have a table group with a field code among others. In Idiorm & Paris I can access it from a Group instance $group like this:

$group->code

How can I document code in Doxygen?

Edit: This question is similar to How to document a variable that isn't really there in Doxygen?, but it's about dynamic members, not about variables.

Edit 2: I am unsure about the right terminology. It is a dynamic member variable or a dynamic property?

Solution

  • Is it impossible to document non-existant class variables in Doxygen? I tried a naked

    /** @var User::email string 
  * Email address
  */

    without a corresponding $email; member variable in the class, but Doxygen valiantly ignored that. I didn't find a command or something to force a documentation of a missing artifact.

    Therefore I experimented with creativedutchmen's suggestion, however Paris does not cope well with already existing member variables, because – I think – the PHP magic method __get() does not get triggered anymore. I see three possible fixes:

    1. unset() the documented member variables in the constructor. With get_class_vars(get_class($this)) this could be done in a parent class. Because my model classes all inherit from a parent class, this would be relatively straightforward.
    2. Modify Paris to ignore already set member variables, but I do not see how without unset().
    3. Name the member variables slightly differently, like appending an underscore, so they don't conflict with the dynamic variables.

    Horrible kludges. To do something at runtime or have additional members to make documentation possible? No thanks.

    I decided to leave the situation as-is and document the model factory methods carefully instead. Most of the time the factory methods contains as parameters the class variables to be able to set them. And even if the factory method does not set all class variables, it is possible to document the missing variables in prose. The class documentation is also a good alternative.

    I award the bounty to creativedutchmen because of thinking out of the box, even if it didn't help me in the end and because I don't want the reputation points to get lost.

    tl;dr

    Don't kludge. Document dynamic member variables in the factory method or in the class overview.