Skip to content
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

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

Open
matttproud opened this issue Feb 9, 2021 · 1 comment

Comments

@matttproud
Copy link
Contributor

@matttproud matttproud commented Feb 9, 2021

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).

@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
Copy link
Contributor

@dmitshur dmitshur commented Feb 10, 2021

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants