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

encoding/xml: bulleted lists badly formatted in documentation #26778

Closed
bcmills opened this issue Aug 2, 2018 · 7 comments
Closed

encoding/xml: bulleted lists badly formatted in documentation #26778

bcmills opened this issue Aug 2, 2018 · 7 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@bcmills
Copy link
Contributor

bcmills commented Aug 2, 2018

The bulleted lists in the doc comments for Marshal, Unmarshal, and perhaps others are indented in a way that confuses the formatter for golang.org/pkg. (It thinks they're code instead of prose.)

screenshot 2018-08-02 at 16 42 16

@bcmills bcmills added Documentation Issues describing a change to documentation. help wanted NeedsFix The path to resolution is known, but the work has not been done. labels Aug 2, 2018
@bcmills bcmills added this to the Unplanned milestone Aug 2, 2018
@cespare
Copy link
Contributor

cespare commented Aug 2, 2018

Isn't this the intentional, hacky workaround for #7873?

@bradfitz
Copy link
Contributor

bradfitz commented Aug 2, 2018

"Working as Compromised"

@bcmills
Copy link
Contributor Author

bcmills commented Aug 2, 2018

Maybe, but to paraphrase a fashion tip: write for the formatter you have, not the formatter you want.

@bradfitz
Copy link
Contributor

bradfitz commented Aug 2, 2018

Um, that's exactly what we did. Did you get the quote backwards?

@cespare
Copy link
Contributor

cespare commented Aug 2, 2018

@bcmills btw you may find my examples listed at #7873 (comment) to be interesting. In at least one place (net/http) we used a different workaround (unicode bullets). Maybe you will be motivated to add your voice to #7873 :)

@bcmills
Copy link
Contributor Author

bcmills commented Aug 2, 2018

Um, that's exactly what we did.

I mean: if we can't render bulleted lists, don't use them at all. (Paragraphs‽)

@cespare
Copy link
Contributor

cespare commented Aug 2, 2018

@bcmills well, we have a lot of instances of this type of list in the stdlib; maybe this bug should be closed? Unless you want to try to make the change across the whole codebase (unlikely to be popular, I imagine).

@bcmills bcmills closed this as completed Aug 2, 2018
@golang golang locked and limited conversation to collaborators Aug 2, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

4 participants