Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Method docstrings are not visually separated #3129

Open
abhro opened this issue Jan 1, 2025 · 0 comments
Open

Method docstrings are not visually separated #3129

abhro opened this issue Jan 1, 2025 · 0 comments

Comments

@abhro
Copy link

abhro commented Jan 1, 2025

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant