0xCAFEBABE/doxypy — Issue #4: Feature request -- the ability to document class variables
Author: jamercee
Created: 2012-01-13 18:18:54+00:00
State: open

It would be really useful if doxypy.py were able to handle class variables conversion to Doxygen format.

In case you're not familiar with Django (which we're using), they make pretty extensive use of class variables in their ORM (object relational mapper). This is an incredibly powerful feature that makes it snap easy to create database record classes for storing, retrieving and querying SQL data sources.

For example:

from django.db import module

class Phone(models.Model):
''' Phone number record '''

''' @var phonenumber
@brief Phone number
'''
phonenumber = models.CharField(max_length=64)

While doxypy.py does a fine job of extracting the commented related to the class (Phone in the example above), the FSM state-machine doesn't seem to know how to grok the comment associated with the phonenumber class variable. If you run doxypy.py in '--debug' mode, it reports:

# FSM: executing (DEFCLASS_BODY -> DEFCLASS_BODY) for line ' .....

It seems to understand it's inside a class definition, but doesn't recognize a variable declaration.

This has unfortunately forced us back to using the Doxygen NON-Docstring sytax

## @var variablename
# @brief Brief description of variables purpose

It's not a terrible solution, but defeats some of the cool pythonic help() features built into the language.

We've spent a bit of time looking through the doxypy.py makeTransition() and the appendCommentLine() code, but the changes required would appear to be more complex than our superficial understanding of what's going on allows.

Thought we'd submit a friendly feature request for any future releases.

Thanks