AnswerDotAI / AnswerDotAI/fastcore

`MarkdownRenderer.__repr__` places the docstring inside a return-docment comment

Open Beginner friendly
#911 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.