Comments (4)
I am not a core dev, but I am not sure that the issue linked above is a sufficiently strong reason to even consider moving something into Base. Technically, there is no reason VS Code just couldn't support DocStringExtensions as a package.
It is my impression that the tendency is to move things out of Base, and be very conservative with standard libraries. A couple of reasons for this are
- extra maintenance burden; a serious bug in Base or the std libs could block a release,
- less flexibility (bugfixes and new features have to wait for a release),
- a more conservative approach to new features and refactoring, as the API is technically frozen for breaking changes until next major release
from docstringextensions.jl.
Thanks for your input @dgleich. The points made earlier in favour of this remaining out of Base
still, as far as I'm concerned, outweigh any possible benefits of inclusion as a stdlib.
I might use these extensions if they were in Base, but perhaps wouldn't bother if they aren't in Base.
Just to make this clear, the dependencies of the package are about as light as you can get. It only depends on stdlibs and there has been, to my knowledge, zero effort spent on improving it's latency so load times could likely be improve with some amount of careful effort if someone felt the need. (If that's what the concern is with regard to including this as a dep?)
Also, Base does seem to have some of this functionality available untemplated through their docview anyway.
Yeah, those were added when we initially implemented docstrings as a kind of "lite" version of some of the features here. They aren't quite as useful though.
Personally, I don't feel there are enough benefits to pushing this into the stdlib, and I'm not going to be pursuing it myself. The vscode issue that kicked this one off is, I feel, a bit of a red herring. Regardless of whether this is in Base
or not, you still have to evaluate code that can do arbitrary things to render the docstrings.
from docstringextensions.jl.
Judging by the number of direct dependents (131) I'd say we're still in the realm of niche usage with the package as it stands considering there's 3824 packages registered in General. Regarding maturity of the code; I've not touched it in a number of years, though there's been a few additions and bug fixes since then that @mortenpi has shepherded along. Doesn't appear to have many long-standing serious bugs, so in that regard it's doing alright. I'd want additional input from other core devs before we considered upstreaming anything.
from docstringextensions.jl.
As a note on the discussion above. It goes both ways too. I might use these extensions if they were in Base, but perhaps wouldn't bother if they aren't in Base.
Also, Base does seem to have some of this functionality available untemplated through their docview anyway. (e.g. in Base will output the following documentation automatically now...)
julia> mutable struct MyTypeSD
x::Int
end
help?> MyTypeSD
search: MyTypeSD
No documentation found.
Summary
≡≡≡≡≡≡≡≡≡
mutable struct MyTypeSD <: Any
Fields
≡≡≡≡≡≡≡≡
x :: Int64
If you want a poor quick imitation for your own documentation without any dependencies, the following suffices... (based on https://github.com/JuliaLang/julia/blob/master/stdlib/REPL/src/docview.jl where much of the automated code above lives...)
function _field_print(T::Type)
pad = maximum(length(string(f)) for f in fieldnames(T))
return string("# Fields\n",
"```\n",
map( (Z) -> string(rpad(Z[1], pad), " :: ", Z[2]), zip(fieldnames(T), T.types) )...,
"```\n")
end
""" With documentation
$(_field_print(MyTypeSD))
"""
mutable struct MyTypeSD
x::Int
end
help?> MyTypeSD
search: MyTypeSD
With documentation
Fields
≡≡≡≡≡≡≡≡
x :: Int64
(Note, it's possible there's additional discussion relevant somewhere out there in the Juila ecosystem, will update if I find anything.)
from docstringextensions.jl.
Related Issues (20)
- How to use alias of AbstractArray instead of the full name? (Feature request) HOT 2
- Display parametric types in a better way? HOT 2
- Remove documentation page for v0.1
- Update CI badges in the README HOT 2
- TagBot trigger issue HOT 7
- The `TYPES` template does not apply to parametric types
- MODULES key not found for `@template` HOT 1
- Doctest failures
- Format docstrings HOT 4
- Considering writing a script to add function signatures to a code base. HOT 5
- Examples of how to use all of the functionality HOT 5
- expected test failure from the incoming `Core.Compiler` changes HOT 3
- Cannot get source for generated functions
- feature request: non-api doc marker HOT 3
- How to show default values and types of keyword arguments? HOT 1
- Update docs to latest version of Documenter HOT 5
- different abbreviations for concrete and abstract types HOT 1
- FUNCTIONNAME inside a function that generates the docstring HOT 7
- Would it be possible to add a TYPEDMETHODLIST abbreviation HOT 2
- Internal errors when (ab)using `@template` HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docstringextensions.jl.