Go: proposal: add illustrations to documentation pages

[ajstarks]

What is the URL of the page with the issue?

Any API documentation URL (for example: https://pkg.go.dev/gioui.org/layout?tab=doc)

What is your user agent?

Mozilla/5.0 (X11; Fedora; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.97 Safari/537.36

What did you expect to see?

I would like to support adding illustrations to documentation pages. Perhaps one method would be to show an image triggered by a magic comment:

```
// Foo does ....
//
func Foo(....)

[dmitshur]

Also see #16666.

[myitcv]

I would like to support adding illustrations to documentation pages. Perhaps one method would be to show an image triggered by a magic comment:

// Foo does ....
//  ![foo illustration](link-to-image.png)
func Foo(....) 

A possible refinement of this suggestion would be to leverage the fact that directives are not included as part of go doc documentation:

package x

// Foo does ....
//godoc:image ![foo illustration](link-to-image.png)
func Foo() {}

and:

$ go doc Foo
package x // import "."

func Foo()
    Foo does ....

[ajstarks]

@julieqiu can you suggest some next steps? (Possibly discussing at the next tools call)

[ajstarks]

Here is a mockup of what it would like:

// Circle makes a filled circle, using percentage-based measures
// center is (x,y), radius r
//godoc:image ![illustration of circle](circle.png)
...

// Ellipse makes a filled circle, using percentage-based measures
// center is (x,y), radii (w, h)
//godoc:image ![illustration of ellipse](ellipse.png)

[julieqiu]

Thanks, @ajstarks! I like this suggestion.

@jayconrod @bcmills for thoughts on using directives for this.

[bcmills]

The Go project has historically resisted adding much in the way of structured formatting to doc comments (https://github.com/golang/go/issues/35947#issuecomment-561721389)

Personally I don't have a strong opinion on the matter either way, but given the history I would be inclined to send this through the proposal process.

See also #25444, #16666, #7873, #25449, https://github.com/golang/go/issues/18342#issuecomment-390774939.

[julieqiu]

@ajstarks - filing a proposal for this issue would be a good next step. See https://github.com/golang/proposal for details.

[ajstarks]

thanks @julieqiu . Do I need to make a new proposal issue? Should the Proposal tag be added to this issue? Is a design doc required at this stage?

[dmitshur]

I think to start it would be sufficient to turn this issue into a proposal by adding the Proposal label, as described in step 1 of https://github.com/golang/proposal#the-proposal-process. That can be done by adding a "proposal:" prefix to the issue title. You may be asked for a design doc as part of step 2.

[ajstarks]

FYI: here is the proposal in more detail:
https://github.com/ajstarks/go-illustration/blob/master/proposal.md

[bcmills]

I note that the proposal suggests that go doc should not render the alt-text for the image.

I think that would put terminal readers at a significant disadvantage vs. the alternative today (explicit URLs), since they wouldn't even know that there was other content available in the documentation. (We probably need to figure out some way to indicate the elided content on the terminal, if not display the content URL.)

[ajstarks]

Perhaps I should be more explicit on alt-text handing. The intention is that agents are free to use the alt-text as they see fit. I also could update the recommendations to include "good" alt-text, assuming that it will be rendered.

[yiyus]

I do not have a strong opinion about this, but I think it would be preferable if the magic comment did not look like one. For example, the magic comment may be: "See figure circle.png (ilustration of a circle)".

[ajstarks]

@yiyus I like the notion of a more natural language approach very much. Do you have an opinion on the relative difficulty of implementation vs. the // godoc:image method?

[bcmills]

@yiyus, @heschik points out that a convention like “See figure ().” might be challenging for authors of non-English documentation.

We have a similar precedent in the // Deprecated: comments for APIs and // Output: comments for Example functions, so perhaps the format here could be something like // Image: <file> (<alt-text>).