search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
123.59k stars 17.61k forks source link

proposal: affected/package: godoc #59965

Closed xrfang closed 1 year ago

xrfang commented 1 year ago

I try to add a piece of YAML code in a package doc comment, but the godoc tool insist to parse it as "list". Here is my question on stackoverflow .

I would like to propose a simple "trick" to the godoc tool, shown in this example:

/*
This is an example of YAML code:

 \- 20230504_170104.293: /api/poll?wait=50&t=06b6f4777a92033c5488cfe2c02f31
    code: 408
    elapsed: 50001
    mesg: no event
    method: GET
  - 20230504_170154.475: /api/poll?wait=50&t=06b6f4777a92033c5488cfe2c02f31
    code: 408
    elapsed: 50001
    mesg: no event
    method: GET
*/

By adding a \ in front of the first "-", the whole indented block is no longer parsed as list (a backslash is not required for the second list item, however...).

I suggest to support "escape" the list marks by backslash (or any other mechanism the implementers think appropriate), and do NOT display that backslash when rendering.

xrfang commented 1 year ago

I found a solution and will update my SO post, this proposal is withdrawn.