There's magical handling in the go/doc package to convert them into “ and ”.

but not, at least in some docs. Bug?

What @dotaheor is saying that these quotes aren't being replaced in synopses.

Ah, that wasn't clear to me. It seems to me that the commentEscape function is not being applied to the synopsis. However, I don't think it should either, since it assumes HTML is end-target output.

Personally, I'd rather see the special handling for the double back-ticks and double single-quote be removed. Go supports unicode, so the rare uses of them could just use the actual unicode characters for them.

I'd rather see the special handling for the double back-ticks and double single-quote be removed.

I'd be happy for us to stop [ab]using them in this way in standard library sources, but note that actually removing that support from doc would be a backward-incompatible change.

CC @griesemer

No, we're not going to remove this handling. Existing docs exist.

Sorry, misunderstood - OK, then we should fix the synopses to do the same replacements. But let's not redefine the doc comment syntax and invalidate existing comments.

I'm wary of this. The replacement logic is done by doc.ToHTML and converts the quotes to “ and ”. On the other hand doc.ToText does no replacement whatsoever. The doc.Synopsis function is used for both outputting to HTML and text. Auto-converting to the HTML entity is a bad for pure text outputs.

Now, if we consistently convert the double single-quotes to the unicode equivalent in all three cases, that seems more appropriate.

I agree. I have a simpler solution if you may. We can handle this in the template render function inside godoc. With just an additional helper.

Currently, it is this {{html .Synopsis}}

We can just port the minimal logic from go/doc and have a new helper. Thus making it
{{html .Synopsis | commentEscape}}

So doc.Synopsis remains unchanged, and we still get to convert the quotes. Albeit with some very minimal code duplication.

Probably we should factor out the nice part from the HTMLEscape part: we can convert quotes in the first pass (for Synopsis and ToText), and then HTMLEscape the result.

@bcmills - Could you clarify your comment a bit ? I was looking to get going with this and wasn't fully sure what the consensus was. Did you mean to say we should convert the quotes for all the 3 functions (ToHTML, ToText and Synopsis) ? HTMLEscapeing after converting quotes will also convert the &ldquote; to &ldquote;.

I believe the primary concern here is that Synopsis is used for text and html output both, so converting to html entities will be incorrect for programs expecting text output.

Or did you mean that we should convert to the unicode character directly, for all 3 cases ? That seems to be a clean solution to me.

Did you mean to say we should convert the quotes for all the 3 functions (ToHTML, ToText and Synopsis) ?

Yes: we should convert the quotes to Unicode characters (“ and ”), and if ToHTML wants to convert them further then it can transform “ to &ldquote; and ” to &rdquote;.

Change https://golang.org/cl/150377 mentions this issue: go/doc: convert to unicode quotes for ToText and Synopsis