Skip to content

go/doc: find a better home for Go documentation features like section headings #44194

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.

Sign up for GitHub

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

Jump to bottom
Closed
matttproud opened this issue Feb 9, 2021 · 3 comments
Closed

go/doc: find a better home for Go documentation features like section headings #44194

matttproud opened this issue Feb 9, 2021 · 3 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.19

Comments

@matttproud
Copy link
Contributor

fluhus/godoc-tricks describes several extended tricks for the Godoc renderer that remain relevant for https://pkg.go.dev. Particularly notable is the technique described as Titles, which can be thought of as naive section headings as demonstrated below with the word "Limitations":

// CreditCard models a lender-backed payment instrument.
//
// Limitations
//
// The type provides no native validation against its issuer.  It is a dumb data type.
type CreditCard struct{}

To date this technique is not substantively mentioned in any of the following:

Considering its utility for information presentation, anchoring, etc., I propose the feature earn proper documentation. I tried to search for an existing bug for this, but the closest thing I could find was #18342. The correct approach would probably involve amending the previous documents somehow (or maybe another).
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Feb 9, 2021
@dmitshur dmitshur added this to the Backlog milestone Feb 10, 2021
@dmitshur dmitshur changed the title Document How to Make Section Headings in Go Documentation go/doc: find a better home for Go documentation features like section headings Feb 10, 2021
@dmitshur dmitshur added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Feb 10, 2021
@dmitshur
Copy link
Contributor

I'll highlight the current documentation at https://golang.org/pkg/go/doc/#ToHTML:

Each span of unindented non-blank lines is converted into a single paragraph. There is one exception to the rule: a span that consists of a single line, is followed by another paragraph span, begins with a capital letter, and contains no punctuation other than parentheses and commas is formatted as a heading.

If we had documentation about writing documentation (similar to https://blog.golang.org/godoc, but as evergreen documentation rather than a blog post), I agree this should be covered there. I don't know if there are plans to do this at this time.

CC @julieqiu, @stevetraut, @griesemer.

@dmitshur
Copy link
Contributor

dmitshur commented Jun 6, 2022

I expect CL 410394 (CC @rsc) will resolve this issue.

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/410394 mentions this issue: _content/doc: document doc comments at go.dev/doc/comment

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Jun 6, 2022
@dmitshur dmitshur modified the milestones: Backlog, Go1.19 Jun 6, 2022
@golang golang locked and limited conversation to collaborators Jun 7, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Go1.19
Development

No branches or pull requests
3 participants
@matttproud @dmitshur @gopherbot