pydoc does not remove '#'-s from doc comments

[tkiss80]

BPO	12630
Nosy	@ncoghlan

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2011-07-24.23:22:19.072>
created_at = <Date 2011-07-24.23:05:00.351>
labels = ['type-bug']
title = "pydoc does not remove '#'-s from doc comments"
updated_at = <Date 2011-07-24.23:22:19.060>
user = 'https://bugs.python.org/tkiss80'

bugs.python.org fields:

activity = <Date 2011-07-24.23:22:19.060>
actor = 'ncoghlan'
assignee = 'none'
closed = True
closed_date = <Date 2011-07-24.23:22:19.072>
closer = 'ncoghlan'
components = []
creation = <Date 2011-07-24.23:05:00.351>
creator = 'tkiss80'
dependencies = []
files = []
hgrepos = []
issue_num = 12630
keywords = []
message_count = 2.0
messages = ['141061', '141062']
nosy_count = 2.0
nosy_names = ['ncoghlan', 'tkiss80']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue12630'
versions = ['Python 3.1']

[tkiss80]

If an entity does not have a docstring, pydoc.getdoc() reads the comment associated with that entity and uses that as the source of documentation. However, inspect.getcomments() returns the raw comment with the comment signs ('#') in it, thus the resulting documentation looks ugly and confusing. Is there a way to solve this problem?

I know that this is not an easy task, because by implementing a specific '#' removing solution, the format of the doc comments would be restricted to conform to that algorithm with little formatting freedom. But maybe someone can come up with a good idea, such as counting '#'-s in the first line and strip all the lines accordingly.

[ncoghlan]

The best solution is to modify the offending code to use real docstrings.

Failing that, a simple explicit "'\n'.join(line.lstrip('#' for line in comment.split('\n'))" (i.e. not as part of pydoc) will handle most cases.

Anything more sophisticated would need to be tailored to the comment format of the code that is missing docstrings.