CODEWITHSUNDEEP
pythondocumentation-generation
HWende
HWende

Reputation: 1705

How to document class attributes with NaturalDocs

Via

"""
  Function: myfunc
  Parameters:
    a - First parameter
    b - First parameter
"""

I can document a function and it gets listed in the class summary. How can I do something similar with attributes? Since I don't declare them in python I was hoping something like

""" ----------------------------------------------------------------------------
  Attributes:
  first - First attribute of the class
  second - Second one
"""

That is not working at all...

Upvotes: 0

Views: 908

Answers (2)

Ferdinand Prantl
Ferdinand Prantl

Reputation: 5709

If you don't declare class attributes explictly - I assume you just assign them values in the constructor - you can put their comments together with the class comment:

"""
  Class: MyClass
  Describe the class here.

  Attributes:
    attr1 - First attribute of the class
    attr2 - Second one
"""
class MyClass:

    def __init__(self, arg1):
        self.attr1 = arg1
        self.attr2 = "attr2"

You can do the same for methods too. It is the simplest way but you won't get the class members listed separately in the index, which is a huge drawback. If you provide a prefix for every class member references in the documentation will work:

"""
  Class: MyClass
  Describe the class here.

  Attribute: attr1
  First attribute of the class

  Attribute: attr2
  Second one
"""
class MyClass:

    # Constructor: __init__
    # Describe the constructor.
    #
    # Parameters:
    #   arg1 - The first argument.
    def __init__(self, arg1):
        self.attr1 = arg1
        self.attr2 = "attr2"

    # Method: method1
    # Describe the method here.
    def method1(self):
        print("method1")

Prefixing the comment is not a problem for methods where the comment is usually put just before the implementation anyway. If you don't declare your attributes explicitly to make natural place for their comment, it will clutter the class comment a little. You could also split the comment to more parts. Notice that you can mix line and block comments.

Two remarks: If you want to use block comments delimited by """ and not just the line comments prefixed by # you have to add the following lines to Languages.txt in the NaturalDocs project directory:

Alter Language: Python

   Block Comment: """ """

Apparently you like the keyword Attribute instead of Property which is recognized by NaturalDocs by default. Add the following to Topics.txt in the NaturalDocs project directory to have it recognized too:

Alter Topic Type: Property

   Add Keywords:
      attribute, attributes

--- Ferda

Upvotes: 1

Thanasis Petsas
Thanasis Petsas

Reputation: 4448

Check the docstrings described here: http://epydoc.sourceforge.net/manual-docstring.html

Variables may also be documented using comment docstrings. If a variable assignment is immediately preceeded by a comment whose lines begin with the special marker '#:', or is followed on the same line by such a comment, then it is treated as a docstring for that variable:

#: docstring for x
x = 22
x = 22 #: docstring for x

Upvotes: 0

Related Questions