AnswerDotAI / AnswerDotAI/fastcore
`MarkdownRenderer.__repr__` places the docstring inside a return-docment comment
- Dominant language
- Jupyter Notebook
- Stars
- 1.1k
- Forks
- 295
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 7
Description
When a function has both a docstring and a trailing docment on its return annotation, `MarkdownRenderer.__repr__` appends the docstring directly after the rendered signature.
Because the signature ends with an inline `#` comment, the docstring becomes part of that comment instead of appearing as the function body.
This is visible through `pyskills.doc()`, which uses `MarkdownRenderer`.
## Reproduction
```python
from pyskills import doc
def f() -> int: # return value
"docstring"
doc(f)
```
Actual output:
```python
def f()->int: # return value"""docstring"""
```
Expected output:
```python
def f()->int: # return value
"""docstring"""
```
A direct fastcore reproduction is:
```python
from fastcore.docments import MarkdownRenderer
def f() -> int: # return value
"docstring"
repr(MarkdownRenderer(f))
```
## Impact
The rendered result is misleading and is not valid as a representation of the original function body: everything after `# return value` is part of the comment.
The issue occurs whenever all three conditions are present:
1. The function has a docstring.
2. The return annotation has a trailing docment.
3. The plain-text representation of `MarkdownRenderer` is used.
## Environment
- fastcore: 2.2.13
- Branch: `main`
## Likely cause
`MarkdownRenderer.__repr__` concatenates the docstring directly onto the rendered `DocmentText`:
```python
def __repr__(self):
doc = str(self.dm)
if self.docs: doc += f'"""{self.docs}"""'
return doc
```
When `str(self.dm)` ends with a return docment, it ends in an inline comment:
```python
)->int: # return value
```
Appending the docstring without a newline places it inside that comment.
The renderer should insert a newline and indentation before the docstring, including appropriate indentation for multiline docstrings.
Contributor guide
Research direction
Start at MarkdownRenderer.__repr__ and reproduce the issue with the fastcore example or through pyskills.doc(). Trace how str(self.dm) is combined with self.docs. Done means the docstring appears on a new, indented line after the return comment, including suitable indentation for multiline docstrings, without changing the rendered signature.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100