Blank line in python function docstring breaks Doxygen special commands

intervort 0
Viewed 28

Adding a blank line in the docstring of a function within a class breaks the parsing of the Doxygen Special Command.

This works

class Foo:
    def __init__(self, val):
        """! This is a public member
        @param val (int): integer input
        """
        self.bar = val

but this does not

class Foo:
    def __init__(self, val):
        """! This is a public member

        @param val (int): integer input
        """
        self.bar = val

Blank lines are fine in docstrings when they are not within class functions, so there's a lack of consistency. And I like the blank line for aesthetic reasons and to break the inputs from the description.

How do I make it work with the blank line?

doxygen python
1 Answers

The version of doxygen is not specified, so I tested with the current version (doxygen 1.9.5) and a default doxygen settings file. Also what exactly is missing is not specified.

The good version will result in:

enter image description here

and the "broken" version will result in (added a 1 to the class so I only need one file):

enter image description here

The problem here is the indentation. Due to the empty line the indentation is reset and the Markdown processing will see the @param line with an indentation >=4 and thus as a code section.

There are a couple of solutions:

  • set MARKDOWN_SUPPORT=NO , not really a solution as this will take away a lot of other nice features.
  • adjust the code: 
          """!
      This is a public member

      @param val (int): integer input
      """
  • adjust the code: 
          """! This is a public member

@param val (int): integer input
      """
userIjX60
Related