Skip to content

integrate the rest of doc comments with generated docs #3408

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
8 of 9 tasks
andrewrk opened this issue Oct 8, 2019 · 3 comments
Open
8 of 9 tasks

integrate the rest of doc comments with generated docs #3408

andrewrk opened this issue Oct 8, 2019 · 3 comments
Labels
contributor friendly This issue is limited in scope and/or knowledge of Zig internals. docs
Milestone

Comments

@andrewrk
Copy link
Member

andrewrk commented Oct 8, 2019

Currently function doc comments and error set doc comments are integrated, but not these:

  • doc comments of struct fields
  • doc comments of enum fields
  • doc comments of union fields
  • doc comments of structs
  • doc comments of enums
  • doc comments of unions
  • doc comments of generic instantiations (related: add generic instantiations to generated docs #3407)
  • doc comments of global variables and constants
  • doc comments of parameters
@andrewrk andrewrk added the docs label Oct 8, 2019
@andrewrk andrewrk added this to the 0.6.0 milestone Oct 8, 2019
@andrewrk andrewrk added the contributor friendly This issue is limited in scope and/or knowledge of Zig internals. label Oct 11, 2019
mattyhall added a commit to mattyhall/zig that referenced this issue Nov 28, 2019
@andrewrk andrewrk modified the milestones: 0.6.0, 0.7.0 Feb 18, 2020
@FlyingWombat
Copy link

I'm not sure if this is what you meant by "the rest of doc comments", but (as of version 0.5.0+10e0b0713) only the first line of a multi-line doc comment is included in the generated HTML documentation.

For std.io.InStream.readAll()
Docs read:

Returns the number of bytes read. If the number read is smaller than buffer.len, it

Doc comment above readAll in lib/std/io/in_stream.zig:34:

/// Returns the number of bytes read. If the number read is smaller than `buffer.len`, it
/// means the stream reached the end. Reaching the end of a stream is not an error
/// condition.

@nektro
Copy link
Contributor

nektro commented Aug 2, 2020

The class view shows the first line as a preview. The function page shows the entire description.

image

vs

image

@nektro
Copy link
Contributor

nektro commented Aug 2, 2020

Although, on your original point, the io.InStream.readAll page actually shows a 404. Though the network tab in devtools shows no activity.

image

@andrewrk andrewrk modified the milestones: 0.7.0, 0.8.0 Oct 17, 2020
@andrewrk andrewrk modified the milestones: 0.8.0, 0.9.0 Nov 6, 2020
@andrewrk andrewrk modified the milestones: 0.9.0, 0.10.0 May 19, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
contributor friendly This issue is limited in scope and/or knowledge of Zig internals. docs
Projects
None yet
Development

No branches or pull requests

3 participants