proposal: x/tools/godoc: add flag to ignore comments beginning with ...

[jons]

i would like to be able to use godoc and swagger simultaneously on a single API (built with the beego framework) in order to provide two sets of documentation, intended for different audiences.

to achieve this, all that is necessary is to tell godoc to ignore comment lines where the first non-whitespace token begins with "@" (swagger already ignores the untagged, godoc-friendly comments). currently, godoc will instead dump these into its output as though they were natural sentences in a paragraph.

[bradfitz]

You may want to expand your proposal to add more details for those not familiar with either Beego or Swagger. (Is Beego relevant to this proposal?).

But in the past, all proposals around adding @MagicAnnotations or other special comments to godoc have been rejected. I don't see how this one would be different.

[groob]

I have successfully used @adams-sarah's project https://github.com/adams-sarah/test2doc in the past. It uses the Apiary format rather than Swagger, but you could extend it to swagger with some engineering effort.

The nice thing is that it does not require creating comments in godoc. The documentation is generated based on your http handler tests.

If you wanted to, you could write the Example format tests to work with test2doc so they'd show up both as godoc examples and as REST API documentation.

[rsc]

As Brad said, we aren't going to change the godoc comment format to hide various lines. @groob's comment about test2doc sounds like a better solution.