docstring: fix handling of empty documentation comments #167
Conversation
doc/syntax.rst
Outdated
|
|
||
| It's also a way to let Sphinx know about types to highlight them in | ||
| e.g. parameter documentation. | ||
|
|
There was a problem hiding this comment.
I wonder whether this is necessary at all, but I don't object to it.
There was a problem hiding this comment.
I can leave that part out. I was contemplating leaving out the entire documentation on empty comments, but thought there's no harm.
There was a problem hiding this comment.
I meant the whole section too by the way. I see no point in documenting this at all, I think anyone would expect this behaviour intuitively.
There was a problem hiding this comment.
Maybe just one sentence in the previous section?
"Empty documentation comments /***/ create the C or C++ Domain directives without documentation."
Or nothing?
There was a problem hiding this comment.
Up to you... I don't feel it's needed but I'd prefer a single sentence to a whole section.
There was a problem hiding this comment.
Dropped it completely. Can be added later if needed.
| struct empty_comment_3 { | ||
| /** Another empty documentation comment. */ | ||
| int description; | ||
| }; |
There was a problem hiding this comment.
What about top level comments? Any chance it might be an issue for autosection? (I plead ignorance by the way.)
There was a problem hiding this comment.
Did not try yet. But seems like it could be a feature! You could use it to end a section (the future version with :members: support).
There was a problem hiding this comment.
Ahahah, maybe...
I'm expecting it to work fine right now, but I'd welcome a unit test for selecting sections before and after one of these at least. In case we inadvertently break it later on.
There was a problem hiding this comment.
Added some top level comments in there, with a c:autosection test. Good enough?
There was a problem hiding this comment.
Yeah, feels complete now. Thanks.
|
Interesting edge case. I think it's good over the covered cases and half expecting my worry about top level comments is unfounded. In which case, looks good to me. Out of curiosity, is this just a pile of things you had laying around or is it being currently driven by actual use cases / requests? |
I was hacking on Mesa documentation a bit, see https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/23145#note_1985368 There were cases where Doxygen+Breathe happily generated documentation if struct members were documented but the struct itself was not. I'm not sure I like to promote that model in Hawkmoth, but I thought adding an empty documentation comment to the enclosing struct would be a nice workaround instead of having to add placeholder text (especially because I was unable to come up with actual documentation in the conversion). And it promptly crashed. 🤦 The warning improvements came from there as well. There were directives with typoed/wrong names or filenames, and there was no warnings, just silently no documentation. |
Sometimes it's handy to add an empty documentation comment to generate
documentation for a symbol without having to add some placeholder
text. Or to include documentation for members/enumerations without
documenting the struct/enum.
Currently, empty documentation comments lead to:
File "docstring.py", line 143, in _remove_comment_markers
while not lines[0] or lines[0].isspace():
~~~~~^^^
IndexError: list index out of range
Fix it and add some tests for it. Mix in some empty and non-empty top
level comments to ensure they still work.
jnikula
force-pushed
the
empty-documentation-comments
branch
from
668eca5
to
02c5119
Compare
Sometimes it's handy to add an empty documentation comment to generate documentation for a symbol without having to add some placeholder text. Or to include documentation for members/enumerations without documenting the struct/enum.
Currently, empty documentation comments lead to:
File "docstring.py", line 143, in _remove_comment_markers
while (not lines[0] or lines[0].isspace()):
~~~~~^^^
IndexError: list index out of range
Fix it and add some tests and documentation for it.