Skip to content

RFC: fix #54664, make at-doc not change when REPL is loaded #55817

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

JeffBezanson
Copy link
Member

This is a possible fix, by more fully separating the core docsystem from the presentation layer. @doc always returns a DocStr or vector of DocStrs, and a new REPL.@showdoc handles parsing markdown and filling in helpful text when no docstring is found.

This allows a new behavior: when you copy a docstring using @doc (@doc foo) bar (considered harmful), if @doc foo returns multiple items there is an error. Previously it would concatenate them into a single markdown document and use that as the new docstring, which seems a bit crazy to me.

This is breaking of course; for your consideration.

@JeffBezanson JeffBezanson added breaking This change will break code docsystem The documentation building system labels Sep 19, 2024
@JeffBezanson JeffBezanson added the triage This should be discussed on a triage call label Sep 26, 2024
@LilithHafner LilithHafner added the needs pkgeval Tests for all registered packages should be run with this change label Sep 26, 2024
@StefanKarpinski
Copy link
Member

Would suggest @docstr instead of @showdoc since show suggests printing rather than returning as string. Would be good to get a legal opinion on whether the current documentation requires the current behavior. Would be good to run PkgEval on this change to see how bad carnage is. Even if we technically can change this (not documented API), if the breakage is too significant, we may not want to anyway.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
breaking This change will break code docsystem The documentation building system needs pkgeval Tests for all registered packages should be run with this change triage This should be discussed on a triage call
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants