Email or username:

Password:

Forgot your password?
Alex's posts Post Back to profile
Alex Schroeder

My program has man pages and now I'm wondering whether I should add a lot more comments to the code itself … maybe even turn it into some sort of literate programming artifact. Then again, I don't know. I haven't ever read good documentation of a program from beginning to end. It's either just simple function references, which is nice, but that already works, no extra required. Or I need to search the web for examples of how to use the functions where I don't understand the documentation. If that's the case, then it would be enough to just writer better documentation for packages and functions.
I guess I'm figuring out whether Knuth is right: "The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other." I saw this quote in Jon Udell's Literate programming in Go where he talks about the code-as-wiki approach falling "far short of the standard set by Donald Knuth".
https://www.infoworld.com/article/3677772/literate-programming-in-go.html

21 February at 13:44 | Open on social.alexschroeder.ch
3 comments
Alex Schroeder

I'm looking at the tools available, like go doc and pgksite and at my program (a "command"), and I'm confused. I think the tools are geared towards the documentation of libraries. For example, my command doesn't export any functions. Why should it? The result is that the documentation tools don't show any of the documentation I have written. In other words, if I want documentation to be available for developers in long form (remember my starting point is literate programming), then the go documentation tools seem to be unsuitable unless I pack it all into a single file. If I write a comment for the main function that says "main calls [serve] when Oddmu is called without arguments and [commands] when called with arguments." then it will not get rendered because main is not exported.

I'm looking at the tools available, like go doc and pgksite and at my program (a "command"), and I'm confused. I think the tools are geared towards the documentation of libraries. For example, my command doesn't export any functions. Why should it? The result is that the documentation tools don't show any of the documentation I have written. In other words, if I want documentation to be available for developers in long form (remember my starting point is literate programming), then the go documentation...

21 February at 22:48 | Open on social.alexschroeder.ch
Alex Schroeder

I learned about go doc -all -u which gives me a cool text file to read, including an introduction from documentation at the package level. Since the output is not in reading order, working links seem essential, however. That'd be the hacking documentation hypertext I'd like to see. go doc doesn't have an option to produce HTML and pkgsite doesn't have an option to show unexported symbols, however. Perhaps what's confusing me even more (the keywords "go", "doc" and "html" are not helping) is that go doc and godoc are two different tools?

I learned about go doc -all -u which gives me a cool text file to read, including an introduction from documentation at the package level. Since the output is not in reading order, working links seem essential, however. That'd be the hacking documentation hypertext I'd like to see. go doc doesn't have an option to produce HTML and pkgsite doesn't have an option to show unexported symbols, however. Perhaps what's confusing me even more (the keywords "go", "doc" and "html" are not helping) is that

22 February at 7:38 | Open on social.alexschroeder.ch
Alex Schroeder

Well, godoc seems to have the same limitation as pkgsite: exported symbols only. So now I'm thinking … and maybe that's my two Perl and Emacs heads showing … perhaps I should just export it all?

22 February at 7:47 | Open on social.alexschroeder.ch
Go Up