Closed nhz2 closed 2 weeks ago
All modified and coverable lines are covered by tests :white_check_mark:
Project coverage is 95.83%. Comparing base (
bd29025
) to head (3dca95e
).
:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.
This makes it clear that it's not an IO
method of peek
but most Base users won't have any idea what a ParseStream
is and that they need to look it up as Base.JuliaSyntax.ParseStream
.
But I think the real problem here is that JuliaSyntax shouldn't add a method to Base.peek
at all but use a module local function for its internal ParseStream peeking.
Yes, either we remove the docstring or make it module local. No need for this to show in docs at all.
Both of those seem like bad options, no? Base.peek
is the right concept, so an overload seems appropriate. Removing the docstring seems weird as well.
Can't we do this level of filtering in Documenter.jl instead?
Okay, how about detecting when the package is put into the sysimage and not add the docstring in that case?
Also, if peek
is the right concept, why does it need a docstring? The generic one should do in that case? I don't add docstrings to all my getindex
methods.
why does it need a docstring?
Because it has additional kwargs that should be documented.
Okay, how about detecting when the package is put into the sysimage and not add the docstring in that case?
Ok, so I think there are a few desirable properties for docstrings added by stdlibs:
Most of that holds for generic packages as well, and this PR is probably not the right place to talk about that anyways.
I think I'll just go ahead and merge this as-is, because it's an improvement. Further steps can be taken in a new PR.
When looking at the help for
peek
in the repl, the current docstring looks like it applies to allIO
, so I added::ParseStream
to make the docstring more specific. See also https://github.com/JuliaLang/julia/issues/54749