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.

[bcmills]

The Go project has historically resisted adding much in the way of structured formatting to doc comments (#35947 (comment))

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, #18342 (comment).

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

[sbinet]

if we go w/ the // Image: <file> directive, could we also devise a way to integrate it somehow with func ExampleXYZ() ?

it would be quite useful and convenient for packages dealing with graphics, not only to be able to document APIs with pictures, but to also document their examples with those.

I guess I am not proposing // Image: to be a reference output for the example (as the image may slightly vary from platform to platform, and it's not as easy than for, say, floating point data to "ignore" noise).
but being able to document the ExampleXYZ function with // Image: and have that image being displayed with the example would go a long way.

[rsc]

In #51082 we discussed and decided not to do this.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[deefdragon]

In #51082 we discussed and decided not to do this.

@rsc just clarifying that you are saying you decided to defer it, not that it was decided that it should not be done right? in That discussion you specifically say that "images remain out of scope for this change" and I read that to mean that discussion was only narrowed to headings, lists, and links.

Regardless, you pointed out some valid issues in that proposal, some being image sizes &resolutions, hints, image sets etc.

Even with that complexity however, I am of the opinion that adding doc image support is just too potentially usefull for documenting complicated Systems and adding examples to graphical libraries.

[rsc]

No change in consensus, so declined.
— rsc for the proposal review group