Doxygen (python) ignores module docstrings

Question

I generate the documentation of my Python code from the docstrings via Doxygen (1.9.1) in addition with doxypypy (git version from today).

My problem is that the docstrings of a do not appear in the generated HTML. This is an example

# -*- coding: utf-8 -*-
"""This is mypackage.a
"""
import mypackage


def bar(bar):
    """
    This is the function named bar.

    The function calls `mypackage.foo()` and returns an 'a'.

    Paramters:
        bar (str): Just a parameter.

    Returns:
        str: Just an 'a'.
    """
    mypackage.foo(bar)
    return('a')

The function bar() is well documented in Doxygen HTML ouptut. But the String This is mypackage.a from the second line of that py-file do not appear anywhere.

The Doxyfile is quite big so I just show you a selection of the options I use.

BRIEF_MEMBER_DESC      = YES
REPEAT_BRIEF           = YES
ALWAYS_DETAILED_SEC    = NO
FULL_PATH_NAMES        = YES
JAVADOC_AUTOBRIEF      = NO
PYTHON_DOCSTRING       = YES
OPTIMIZE_OUTPUT_FOR_C  = NO
OPTIMIZE_OUTPUT_JAVA   = YES
OPTIMIZE_FOR_FORTRAN   = NO
OPTIMIZE_OUTPUT_VHDL   = NO
OPTIMIZE_OUTPUT_SLICE  = NO
MARKDOWN_SUPPORT       = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_PACKAGE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_CLASSES  = YES
EXTRACT_LOCAL_METHODS  = YES
EXTRACT_ANON_NSPACES   = NO
RESOLVE_UNNAMED_PARAMS = YES
HIDE_UNDOC_MEMBERS     = NO
HIDE_UNDOC_CLASSES     = NO
HIDE_FRIEND_COMPOUNDS  = NO
HIDE_IN_BODY_DOCS      = NO
INPUT                  = ../src/mypackage
FILE_PATTERNS          =
RECURSIVE              = YES
FILTER_PATTERNS        = *.py=./py_filter
GENERATE_HTML          = YES

The FILTER_PATTERNS is used because of doxypypy. But the problem also occurs if I do not use this filter. So I would assume this problem is not related to doxypypy.

Maybe this is the right answer? stackoverflow.com/a/58701/4865723 But I am wondering why I need extra commands like @package. Shouldn't it be obvious that the first docstring in a py file is the module/package documentation? — buhtz
– buhtz, Commented Mar 7, 2022 at 11:14
Looks like related to github.com/doxygen/doxygen/issues/9188 — albert
– albert, Commented Mar 7, 2022 at 11:23
Even if I remove the first line # -*- coding: utf-8 -*- the module docstring do not appear. — buhtz
– buhtz, Commented Mar 7, 2022 at 12:54
When I remove the # line I see the line "This is mypackage.a` in the file namespaceaa.html (my file is called aa.py). (I had, in this case, to remove the INPUT and FILTER_PATTERNS as they are not applicable in the small test case). A number of remarks: "he Doxyfile is quite big so I just show you a selection of the options I use." why not use doxygen -x showing the differences between the used file and the default settings. Also read about the PYTHON_DOCSTRING settings (not relevant for the showing but for the layout, I would prefere NO). — albert
– albert, Commented Mar 7, 2022 at 13:37
Thanks a lot for your tips. I can reproduce the Bug with the current upstream version of Doxygen, without doxypypy involved. Is this an answer or should we just close that question? — buhtz
– buhtz, Commented Mar 7, 2022 at 15:33

cup · Accepted Answer · 2023-01-03 23:05:56Z

1

A bit late. Try the following docstring. It just needs the ! after the quotes to get picked up by doxygen. Use @param and @return to get the parameter and return value highlights in the generated document.

def bar(bar):
    """!
    This is the function named bar.

    The function calls `mypackage.foo()` and returns an 'a'.

    @param bar (str): Just a parameter

    @return str: just an 'a'

    str: Just an 'a'.
    """
    mypackage.foo(bar)
    return('a')

answered Jan 3, 2023 at 23:05

cup

8,5284 gold badges23 silver badges48 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

albert Over a year ago

You should also the setting PYTHON_DOCSTRING = NO, see documentation and my comment with the question.

Collectives™ on Stack Overflow

Doxygen (python) ignores module docstrings

1 Answer 1

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related