Comments (5)
Unfortunately, through no fault of this package, I'm not going to be able to use the good versions until JuliaLang/julia#36906 is fixed upstream
JuliaLang/julia#37048 should hopefully resolve that one.
from docstringextensions.jl.
Same also applies if I replace
@doc "..." CameraConfig
@kwdef struct CameraConfig ... end
with
@doc "..."
@kwdef struct CameraConfig ... end
from docstringextensions.jl.
Can you confirm that you are at 339cd6d for master
?
With this test file:
module Test
import Base: @kwdef
using DocStringExtensions
abstract type Pose end
abstract type CameraIntrinsics end
@template TYPES =
"""
Fields:
$(TYPEDFIELDS)
---
$(DOCSTRING)
"""
@doc """
Camera configuration.
Defines the intrinsics and extrinsics of an ideal pinhole camera.
""" CameraConfig
@kwdef struct CameraConfig
"""Pose (position and orientation) of the camera eye."""
cameraEyePose::Pose
intrinsics::CameraIntrinsics
end
end
You'll note the following
julia> include("/home/mike/test.jl")
WARNING: replacing module Test.
Main.Test
julia> Docs.meta(Test)[Docs.@var(Test.CameraConfig)].docs[Union{}].data
Dict{Symbol,Any} with 5 entries:
:typesig => Union{}
:module => Main.Test
:linenumber => 19
:binding => Main.Test.CameraConfig
:path => "/home/mike/test.jl"
:fields
is not captured since the @doc
call does not capture the actual struct
definition. This is a limitation how the docsystem works. If you instead apply the docstring directly to the definition:
"""
Camera configuration.
Defines the intrinsics and extrinsics of an ideal pinhole camera.
"""
@kwdef struct CameraConfig
"""Pose (position and orientation) of the camera eye."""
cameraEyePose::Pose
intrinsics::CameraIntrinsics
end
julia> include("/home/mike/test-2.jl")
Main.Test2
julia> Docs.meta(Test2)[Docs.@var(Test2.CameraConfig)].docs[Union{}].data
Dict{Symbol,Any} with 6 entries:
:typesig => Union{}
:module => Main.Test2
:linenumber => 0
:binding => Main.Test2.CameraConfig
:path => ""
:fields => Dict(:cameraEyePose=>"Pose (position and orientation) of the camera eye.")
And the template is correctly applied:
help?> Test2.CameraConfig
Fields:
• cameraEyePose::Main.Test2.Pose
Pose (position and orientation) of the camera eye.
• intrinsics::Main.Test2.CameraIntrinsics
─────────────────────────────────────────────────────────────────
Camera configuration.
Defines the intrinsics and extrinsics of an ideal pinhole camera.
@doc "..." @kwdef struct CameraConfig ... end
That is not the right syntax to add a docstring to CameraConfig
. Your @doc "..."
doesn't apply to the next line, here it is just searching the docsystem for a docstring attached to "..."
, which won't find anything.
Bottom line is: don't use @doc
when you're trying to document things, it'll likely be do the wrong thing. Just use bare strings above definitions. Hope that all helps.
from docstringextensions.jl.
Thanks for these responses @MichaelHatherly!
I'm pretty sure I'm on the latest revision:
pkg> add DocStringExtensions#master
pkg> status DocStringExtensions
...
[ffbed154] DocStringExtensions v0.8.2 `https://github.com/JuliaDocs/DocStringExtensions.jl.git#master`
Manifest.toml says it's using git tree hash 8990557a11a984254a2fa4f69f24ff861b080a03
. I'm not sure how to map that to a commit, and people seem to struggle with that on Discourse as well.
Here's what I'm seeing:
Works
-
"""My docstring""" @kwdef struct CameraConfig ... end
-
"""$(raw"""My docstring with ``\LaTeX``""")""" @kwdef struct CameraConfig ... end
-
(Thanks for pointing out that the non-parentheses macro invocation syntax doesn't work here)
@doc(raw"""My docstring with ``\LaTeX``""", @kwdef struct CameraConfig ... end)
Doesn't work
-
(no docstring gets attached -- intentional on the part of Julia)
raw"""My docstring with ``\LaTeX``""" @kwdef struct CameraConfig ... end
Unfortunately, through no fault of this package, I'm not going to be able to use the good versions until JuliaLang/julia#36906 is fixed upstream -- having the wrong view source link is too big of a problem, so I'm stuck with the @doc "..." CameraConfig; @kwdef struct CameraConfig ... end
workaround which loses field docstrings. Thanks for fixing the issue in DocStringExtensions
and for explaining all the above!
from docstringextensions.jl.
Omg, thanks!!
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 7
- 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.