Issue with class attributes interpretation

[ofouillo]

Following previous comment I did about class attributes translation into doxygen format, you have update @param inti @var. Unfortunately the fix is not so easy.... The syntax is different and the location of the comments is different as well. Actually you have:

@brief desc.....

@var var1 desc1...

@var var2 desc2...

class myClass: ...

But the syntax for doxygen is:

@brief desc.....

class myClass:

@var var1

#   desc1...
## @var var2
#   desc2...
...

I don't know why they have choose this approach in doxygen. I prefer yours (find it more coherent) but it's not working.

[ofouillo]

Sorry I didn't know the message was preprocessed

Here is the actual syntax

## @brief     Desc....
#
#
# @var      var1    desc1...
# @var      var2    desc2...
#

class SeedCache:

    ## @brief         desc...
    #
    def myFunc(self):
    ....

And How it should be

## @brief     Desc....
#
#

class SeedCache:
    ## @var     var1
    #  desc1...
    ## @var     var2
    #  desc2...

    ## @brief         desc...
    #
    def myFunc(self):
    ....

Thanks

[Feneric]

I should know better than to make assumptions based on behaviors of other keywords. OK, I believe it's fixed now, but please try it out and let me know.

[rockg]

Looking at the test files I don't think it's completely right. The "@var" tags need to be after the class, but they look to be above the class (in particular, sample_google.out). Also, it seems like the "@namespace" tag has similar behavior to "@class" and "@fn" in that it destroys all the documentation in that block. Is it worth contacting doxygen and seeing if this is a bug or if we are missing something?

[Feneric]

I'm not sure I follow. Are you saying that the @var tags can't be within the class documentation block at all?

Using namespaces is optional. We definitely don't want to remove them, as they're (so far as I know) the only way to get real hierarchical listings for Python source within Doxygen. It'll probably end up being a personal preference choice whether the hierarchy or the enhanced per class display gets activated.

[rockg]

That is my understanding and consistent with what ofouillo indicates. When they "@var" is within the class documentation it does the same as all the other tags, destroying the other comments.

On namespaces I wonder if changing the placement would allow for hierarchy and enhanced class display. It would seem weird that only one is allowed. I just played with removing it and the class display was better but I didn't move it within the comment block. I can spend a few moments trying it out.

On Tue, Jul 9, 2013 at 7:56 PM, Eric W. Brown notifications@github.comwrote:

I'm not sure I follow. Are you saying that the @varhttps://github.com/vartags can't be within the class documentation block at all?

Using namespaces is optional. We definitely don't want to remove them, as they're (so far as I know) the only way to get real hierarchical listings for Python source within Doxygen. It'll probably end up being a personal preference choice whether the hierarchy or the enhanced per class display gets activated.

— Reply to this email directly or view it on GitHubhttps://github.com/Feneric/doxypypy/issues/4#issuecomment-20713711 .

[ofouillo]

Yes rockg is perfectly right. @var tags have to be in the core of the class with the right indent, not in its documentation block.

[Feneric]

We can remove the @var tag completely and it won't treat attributes in docstrings as being special. We can't really take them out of the block without messing up other things (like doctests, for example). For my use it's okay if Doxygen doesn't do anything with class attributes, but please tell me what's best for your use cases.

[ofouillo]

On my side I would really like that Attributes get extracted properly so they have their description attached in the doc. It's important in the doc to know the attributes of the class. Since in python trend is not much to use accessor and mutators.

[Feneric]

OK, I found a way that isn't too ugly. Please try it out and see how it works for your use case.

[ofouillo]

Hi, There is only a simple problem now, the indent. @property looks nice but it needs to be indented as the class content. Else it breaks everything.

[Feneric]

OK, how about now?

[ofouillo]

It works fine now. Thanks a lot. I was using it on a small code. I will try it on some more code now. It helps a lot. Thanks again for the support

[Feneric]

You're welcome, I'm glad it's working for you now.