Add support for doc comments

[lod]

Sphinx supports doc comments in the form of #:.

This is also part of the expected and documented syntax for the google and numpy formats, supported in the sphinx implementation but not here.

The format isn't formalised in a PEP, but it is fairly widely used and should be supported. If a decision is made not to support it I believe that should be formally documented, especially in relation to the google and numpy format support.

• Sphinx documentation of #: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoproperty
• Example in the google demo source https://github.com/twisted/pydoctor/blob/master/docs/google_demo/__init__.py#L222
• Missing attr3 and attr4 documentation in the google demo https://pydoctor.readthedocs.io/en/latest/docformat/google_demo/google_demo.ExampleClass.html
• Example in the numpy demo source https://github.com/twisted/pydoctor/blob/master/docs/numpy_demo/__init__.py#L289
• Missing attr3 and attr4 documentation in the numpy demo https://pydoctor.readthedocs.io/en/latest/docformat/numpy_demo/numpy_demo.ExampleClass.html
• Sphinx implementation code https://github.com/sphinx-doc/sphinx/blob/17a32d963ac6ceaa0b29c005beb84e1447df0b41/sphinx/pycode/parser.py#L370-L395

[tristanlatr]

Hello @lod and thanks for your interest in pydoctor.

This feature would be great to have I agree! And the fact we do have this kind of docs in our demo makes it embarrassing not to support it. The main issue is that we don’t have the comments/tokens information in the model at the moment, we only work with the abstract syntax tree from the standard library.

I believe this could be implemented as a token aware ast transformer that would create legit Constant nodes (inline docstrings) based on doc comments. This way we don’t have to touch the astbuider code or only to add the preprocessing step.

[tristanlatr]

What happens if both syntax are used ? I'de suggest that we leave a warning and the inline docstring is used.