When `@private` annotation is used to hide a member, it still appears in the 'View source' code extract.

[elliot-100]

Problem Description

Docs says:

If you want to override the default behavior for a particular item, you can do so by including an annotation in its docstring:
@private hides an item unconditionally.

However I was surprised to find it still appears in the 'View source' code extract.

Steps to reproduce the behavior:

Create e.g. doc.py:

"""Module docstring."""

MODULE_CONSTANT = "MODULE_CONSTANT"
"""@private member docstring."""

def my_func() -> None:
    """@private function docstring."""
    return None

2. Run pdoc ./doc.py
3. Generated doc.html doesn't initially show anything after 'Module docstring.', as expected. However if you open the 'View Source' dropdown, the entirety of the source is shown.

System Information

pdoc: 14.5.1
Python: 3.10.11
Platform: Windows-10-10.0.22631-SP0

[aaronsteers]

+1 to ask for additional clarity here.

I've been stymied by this also. I assumed I need to import private from somewhere and then use it as decorator - but I don't see any examples and to my knowlege private is not a Python built-in decorator. There are third party libraries like this one, but that seems like a big leap for us to know.

[elliot-100]

@aaronsteers it is not a Python decorator but an annotation in the docstring, and the example above does work for me in that it blocks generation of HTML text documentation for the constant and the function - but not in the source code snippet. I don't think it is intended to work for modules as there is separarate documentation on that.

Also to add --no-show-source does block generation of all source code snippets as expected.

[mhils]

Generated doc.html doesn't initially show anything after 'Module docstring.', as expected. However if you open the 'View Source' dropdown, the entirety of the source is shown.

This is expected behavior, but I agree we can make it more clear in the documentation!

Also to add --no-show-source does block generation of all source code snippets as expected.

Can you clarify please?

[elliot-100]

Thanks @mhils - happy with a documentation amendment to make expected behaviour clear.

Re my comment on --no-show-source: I was noting that it is possible to completely eliminate the item from the generated docs - at the expense of eliminating all source snippets. But that thought should have stayed in my head ... ;-)