Hi,

I have a project with mixed types of comments - (1) some are doxygen style, (2) most just have a vanilla docsting and (3) I am trying to introduce doxypy style commenting.

My problem is that when I enable inline sources the line numbers are using the line numbers in the input filtered code and not the original code. This seems to stack, so methods in a long source file will have a larger diff between the "real" line numbers and the ones shown in the html. It might look something like this:

Definition at line 91 of file FileWrapper.py.

    00096                                   :
            """Clone to file by writing it to the hard drive.

Where the source looks like:

    91      ## Clone the file to another file.
    92      #
    93      # @param path The path needed to write the file to a file.
    94      # @returns Trace amounts of file on the hard drive.
    95      def copy_doxygen( self, path ):
    96          """Clone to file by writing it to the hard drive.
    97          """
    98          filehandle = open( path, 'wt' )
    99          filehandle.write( self.text )
   100          filehandle.close()
   101          return

My doxygen configuration file compared to a vanilla one:

$ diff Doxyfile-modified Doxyfile-vanilla 
28c28
< PROJECT_NAME           = "doxypy + line numbers"

---
> PROJECT_NAME           =
38c38
< PROJECT_BRIEF          = "Simple test of doxypy + line numbers"

---
> PROJECT_BRIEF          =
119c119
< FULL_PATH_NAMES        = NO

---
> FULL_PATH_NAMES        = YES
184c184
< TAB_SIZE               = 4

---
> TAB_SIZE               = 8
312c312
< EXTRACT_ALL            = YES

---
> EXTRACT_ALL            = NO
619c619
< FILE_PATTERNS          = *.py

---
> FILE_PATTERNS          =
690c690
< INPUT_FILTER           = /usr/bin/doxypy

---
> INPUT_FILTER           =
726c726
< SOURCE_BROWSER         = YES

---
> SOURCE_BROWSER         = NO
731c731
< INLINE_SOURCES         = YES

---
> INLINE_SOURCES         = NO

/P

In order to run on Windows, the input filter must be something like

INPUT_FILTER = "python ../src/doxypy.py --autobrief"

instead of :

INPUT_FILTER = "../src/doxypy.py --autobrief"

Otherwise doxygen will complain about not being able to run ".."

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

I compile documents for a large financial system which makes use of a large number of formulas.

I've noticed that on a python file which contains an error in the LaTeX formula the following can occur:

• Processing of the document fails silently
• Another image is substituted in place of the image we expect to see, creating nonsense documentation.

There's nothing in the stdout to suggest what might be going wrong.

Looking for suggestions on how to fix this!

At least doxygen for php is able to document parameter types. It is very important to be able to document the expected parameter types.

Check http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam

This is the syntax currently used for PHP, I know that this may not work for Pyhton because we do not have the $ and we'll not be able to detect if the datatype is specified or not.

@param  datatype1|datatype2 $paramname description