proposal: go/doc: 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 ....
//  ![foo illustration](link-to-image.png)
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.