Skip to content

Method docstrings are not visually separated #3129

Open
@abhro

Description

@abhro

When using the "Live Docs" feature, the different methods for a function are not separated, and it's not always clear where the docs for one method starts and another begins.

The following example is created after importing DataFrames.jl in a blank notebook and looking up help for Base.ndims:

Method signatures are usually a good indicator of a docstring starting, but since the docstrings can also end with examples, it's not easy to visually search through the doc box to find the right method.

In contrast, Documenter.jl uses a thin line to separate method docs, which make it (at least a little) easier. Image taken from https://dataframes.juliadata.org/stable/lib/functions/#Base.ndims:
DataFrames jl documenter website Pluto issue

The issue is also visible in the cell renders, i.e. when you're defining multiple methods each with their own docs and the docs get collapsed together:

MWE pdf file (relevant section is output of 2nd cell): Interesting analysis.pdf

MWE Pluto.jl notebook
### A Pluto.jl notebook ###
# v0.20.4

using Markdown
using InteractiveUtils

# ╔═╡ b0984797-5f5c-4579-9e7b-6f15827355be
"""
	f(x::Int)

Return 3
"""
f(x::Int) = 3

# ╔═╡ cc54c663-5756-4979-b136-8da6eb7f3a5c
"""
	f(x::Real)

Return 3.0
"""
f(x::Real) = 3.0

# ╔═╡ Cell order:
# ╠═b0984797-5f5c-4579-9e7b-6f15827355be
# ╠═cc54c663-5756-4979-b136-8da6eb7f3a5c

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions