Please, see this other example https://github.com/golang/tools/blob/master/go/loader/doc.go
For that case, I hope in future something merges all the good stuff existing in go practices mixed with the simplicity and freedom of MD, and some proper helpers like i did here https://github.com/mh-cbon/emd Go source code is meant to be read by humans and merely processed by > machines. It should not be made harder for humans to read in order to make > it easier for machines to read. > > If the godoc presentation needs improving, that's a fair point, but it's a > machine's job to do a better job with human input, not the other way around. > I don't figure out how the machine could invent the *proper* formatting intents I can t insert. That markup is not intended to make it easier in any ways for a machine, its chosen to make it possible for a writer to intentionally format the text rendering. (in total opposite of current doc conventions, yes) For a reader, yes, it needs supports of a software to make it *strictly* human readable. I might have been adventurous in that idea, maybe. On Sunday, April 9, 2017 at 7:11:51 PM UTC+2, Rob 'Commander' Pike wrote: > > Go source code is meant to be read by humans and merely processed by > machines. It should not be made harder for humans to read in order to make > it easier for machines to read. > > If the godoc presentation needs improving, that's a fair point, but it's a > machine's job to do a better job with human input, not the other way around. > > -rob > > > On Sun, Apr 9, 2017 at 10:03 AM, <mhh...@gmail.com <javascript:>> wrote: > >> That s a good question. >> >> I could also reverse it, why godoc then ? >> >> >.< >> >> This said, I don t feel like it is so difficult to read. >> >> I believe the fact it is a markup language opens capabilities >> which are not available to raw comments. >> >> One middle way, might be to have a doc file per package, >> much like on github/gitlb project a md file is displayed >> when such file exists. >> >> On Sunday, April 9, 2017 at 1:55:14 PM UTC+2, Jan Mercl wrote: >>> >>> On Sun, Apr 9, 2017 at 1:21 PM <mhh...@gmail.com> wrote: >>> >>> > TLDR: >>> >>> Who wants to read markup language instead of normal, easy for human >>> readable comments? >>> >>> -- >>> >>> -j >>> >> -- >> You received this message because you are subscribed to the Google Groups >> "golang-nuts" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to golang-nuts...@googlegroups.com <javascript:>. >> For more options, visit https://groups.google.com/d/optout. >> > > -- You received this message because you are subscribed to the Google Groups "golang-nuts" group. To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
