docs: include summarized information in the extended documentation mode
#57108
+146
−114
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
When a binding does not have documentation, we return the result of
`summarize(::Binding)` as fallback documentation. While this summary
itself is often quite useful, it is not displayed when the binding does
have documentation, e.g. `help?> Base.Compiler.InferenceResult`:
```julia
help?> Base.Compiler.InferenceResult
...
result::InferenceResult
A type that represents the result of running type inference on a chunk of code. There are two constructor available:
• InferenceResult(mi::MethodInstance, [𝕃::AbstractLattice]) for regular inference, without extended lattice information included in result.argtypes.
• InferenceResult(mi::MethodInstance, argtypes::Vector{Any}, overridden_by_const::BitVector) for constant inference, with extended lattice information included in
result.argtypes.
```
I believe allowing summary information to be included someway could be
useful, so this commit modifies the behavior in extended documentation
mode to include the result of `summarize` at the end of the documentation.
Now ``help?> ?Base.Compiler.InferenceResult`` would look like:
```julia
help?> ?Base.Compiler.InferenceResult
... # the same contents as what rendered in the regular documentation mode
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Extended information found for private binding Compiler.InferenceResult.
Summary
≡≡≡≡≡≡≡
mutable struct Compiler.InferenceResult
Fields
≡≡≡≡≡≡
linfo :: Core.MethodInstance
argtypes :: Vector{Any}
overridden_by_const :: Union{Nothing, BitVector}
result :: Any
exc_result :: Any
src :: Any
valid_worlds :: Compiler.WorldRange
ipo_effects :: Compiler.Effects
effects :: Compiler.Effects
analysis_results :: Compiler.AnalysisResults
is_src_volatile :: Bool
ci :: Core.CodeInstance
ci_as_edge :: Core.CodeInstance
```
Additionally, this commit refactors the internal implementation of the
help mode in REPL.jl to improve extensibility for future enhancements.
aviatesk
added
docs
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
When a binding does not have documentation, we return the result of
summarize(::Binding)as fallback documentation. While this summary itself is often quite useful, it is not displayed when the binding does have documentation, e.g.help?> Base.Compiler.InferenceResult:I believe allowing summary information to be included someway could be useful, so this commit modifies the behavior in extended documentation mode to include the result of
summarizeat the end of the documentation. Nowhelp?> ?Base.Compiler.InferenceResultwould look like:Note that it only changes the behavior of the extended documentation mode within REPL, and the existing behavior of
@docoutside of REPL doesn't change at all.Additionally, this commit refactors the internal implementation of the help mode in REPL.jl to improve extensibility for future enhancements.