Nicer HTML markup for godoc: Needed? Wanted?
Volker Dobler
and methods. But for longer docs the html output is a bit
unstructured. E.g.:
- html/template: There are sections ("Introduction", "Errors",
etc.) but they are hard to see, as comment as well as html
- encoding/xml.Marshal(): uses bullet list to describe the
rule of the selection of the XML elements name which are
formatted as <pre> blocks in html. (Which is okay but ul
would be nicer for me).
This might not be a big issue for the "small", self-contained
standard packages (maybe with the two exceptions mentioned
above) but might hurt documenting larger 3rd party packages.
I did not find much about plans to enhance godoc in this area
on golang-nuts so I played around a bit and it would be easy
to introduce headings and ul/ol in the html output (almost)
_without_ additional markup in the comments:
List can be identified by their formatting (indented block,
each sub block starts with a list marker like '-' or 'o', the
rest of block is properly indented, etc.). Like the list above.
Heading could be identified in a comment if it is
- just some few words without trailing '.'
- preceded by two blank lines
- followed by one blank line
This would format e.g. the section "Introduction", "Errors",
"Context", "A fuller picture" in html/template as heading.
Personally i would prefer a tiny little bit of markup in the
comments for headings, namely underlining the headlines
in the form
//
// My Headline
// ---------------
// Normal text
just because this makes visual scanning the comments
easier if you look for a section, especially if you do not
no its exact name to search for.
The lists detection and the first version of the headline
detection do not need any "markup": Comments stay
easy readable comments and happen to be formatted as
headings and list if the conform to some layout (which
should look nice and natural as a comment).
Is there interest in a CL? If yes: Which layout/formatting?
Should this be postponed until issues 2465, 2464, 1000
and/or 2063 are fixed?
Volker
Jan Mercl
List can be identified by their formatting (indented block,
each sub block starts with a list marker like '-' or 'o', the
rest of block is properly indented, etc.)
Heading could be identified in a comment if it is
- just some few words without trailing '.'
- preceded by two blank lines
- followed by one blank line
Is there interest in a CL?
Volker Dobler
> On Tuesday, November 22, 2011 10:45:30 AM UTC+1, Volker Dobler wrote:
>
> > List can be identified by their formatting (indented block,
> > each sub block starts with a list marker like '-' or 'o', the
> > rest of block is properly indented, etc.)
>
> I think indented comments are already taken as "render as code" (fixed font
> over in a light gray background box).
>
has the format if a list: Output it as a list; if not output as
code as usual.
> > Heading could be identified in a comment if it is
> > - just some few words without trailing '.'
> > - preceded by two blank lines
> > - followed by one blank line
>
> I believe gofmt normalizes blank lines to exactly one, at least between top
> level declarations.
Yes and no: gofmt collapses a sequence of blank lines
_outside_ of a comment block into a single one but not
inside a comment.
>
> > Is there interest in a CL?
>
> I prefer the current simplicity of godoc while it "interprets" the comments
> into HTML and would like to keep it as it is.
Seems I was unclear: godoc will stay simple and interpret comments
into html as is. My suggestion was to "do a bit more" interpretation:
Taking a comment like
/*
Introduction
This does a and b while preserving c.
Details
The following is checked
- foo
- bar
- any baz
*/
and interpreting it as
<h3>Introduction</h3>
<p>This does a and b while preserving c.</p>
<h3>Details</h3>
<p>The following is checked</p>
<ul>
<li> foo</li>
<li> bar</li>
<li> any baz</li>
</ul>
whereas some indented text in a comment like
/*
Some text
- minus signs are ...
other indented stuff
*/
would _not_ be interpreted as an ul but stay preformated
text.
Steve McCoy
OmarShariffDontLikeIt
use markdown? That would be pretty cool.
Volker Dobler
On Nov 22, 2:31 pm, OmarShariffDontLikeIt
<omarshariffdontlik...@gmail.com> wrote:
> Sounds and looks a bit like markdown. Could the comments in Go just
> use markdown? That would be pretty cool.
I don't think that would be covered by the "write good and nice
comments without special markup (no Javadoc nonsens)"-idea behind
godoc.
André Moraes
The textual description of the docs are intended for human reading and
understanding.
The samples can be made, like pointed before, by indenting the code.
More than that could lead to the confusion and hard to read comments
on Java code, sometimes you need to call javadoc to understand what is
written on the comment, even if you can read the raw source code.
Linking to other parts of the documentation should be done by the
information from types used and not hand written by people.
Also godoc must be nice to the command line since some people
(including me) use the cli version of godoc for fast finding of
something I already known.
Take a look at the gorilla doc page
(http://gorilla-web.appspot.com/pkg/gorilla/mux/) the page has a
better visual than the golang.org default, but If you look directly to
the gorilla source code you can still undestand what is written,
something that is not true for some java code.
I don't known how rodrigo (gorilla author) made that page but I don't
think he rewrote all the doc just to make it look that nice.
--
André Moraes
http://andredevchannel.blogspot.com/
Christian Siefkes
> I did not find much about plans to enhance godoc in this area
> on golang-nuts so I played around a bit and it would be easy
> to introduce headings and ul/ol in the html output (almost)
> _without_ additional markup in the comments:
> Is there interest in a CL? If yes: Which layout/formatting?
I think it would be great to have some options for unobtrusive markup in
commments, whether Markdown or anything self-made. Markdown strikes me as
unobtrusive enough:
# Section title
- List item
*italics*
**bold**
`monospace`
[inline link](http://golang.org/)
But any other, lightweight syntax would be fine as well.
Christian
--
|------- Dr. Christian Siefkes ------- chri...@siefkes.net -------
| Homepage: http://www.siefkes.net/ | Blog: http://www.keimform.de/
| Peer Production Everywhere: http://peerconomy.org/wiki/
|---------------------------------- OpenPGP Key ID: 0x346452D8 --
Progress isn't made by early risers. It's made by lazy men trying to find
easier ways to do something.
-- Robert Heinlein
Rodrigo Moraes
> I don't known how rodrigo (gorilla author) made that page but I don't
> think he rewrote all the doc just to make it look that nice.
Thanks for the compliment but it uses pure godoc (an old version
hacked to work on App Engine). I just used lots of blank lines and
what we have.
I miss some simple formatting options. A simple markup for headings,
lists and inline code would definitely be nice to have. It wouldn't
make the source less readable; just offer a few basic options and it
won't clutter docs.
+1 for this (markdown could it be, and doesn't need to be a full blown
implementation; or whatever simple markup which allows us to create a
little richer docs).
-- rodrigo
Rodrigo Moraes
> (http://gorilla-web.appspot.com/pkg/gorilla/mux/) the page has a
> better visual than the golang.org default, but If you look directly to
> the gorilla source code you can still undestand what is written
Sidenote: I wanted to have inter-titles. Because there's no such thing
in godoc, the docs are more verbose than they should be -- I added a
little prose to connect the dots; otherwise sections would be kinda
floating in the air without cohesion. The result is of course harder
to scan and use as reference.
-- rodrigo
Andrew Gerrand
Rodrigo Moraes
> The one thing I find lacking is a means of writing headings. The goinstall
> docs, for example, have several sections of text that should be demarcated
> somehow:
> http://golang.org/cmd/goinstall/
Yes, if I could choose one thing it would be headings. Lists can be
done with pre-formatted text. Bold and italics are not really needed
and can be avoided. Inline <code> would be nice -- I'd like to
differentiate `code` in the middle of narrative docs, but I can live
without that too.
Lack of headings, tough, makes docs harder to read *and* write.
-- rodrigo
Steve McCoy
Andrew Gerrand
I think Volker's idea for parsing headings is pretty good and nonintrusive, and it would already work for goinstall's documentation, at least. Two blank lines followed by a nonempty, non-indented, non-punctuated line and a blank line seems conventional and unambiguous.
Mark Summerfield
Even if you don't want to create or adopt a markup it seems a pity that
there are almost no hyperlinks. For example, the bytes package's
description refers to the strings package but that isn't a link. And
many functions refer to other functions (although usually ones nearby).
Some conventions would probably make it possible to add links. For
example:
Match packages for hyperlinking:
\pL+(\.\pL+)*\s+package\b
Match functions for hyperlinking:
[A-Z]\pL+[(]
(This would require the adoption of Foo() rather than Foo for function
names which IMO is nicer anyway since Foo in code is a function
reference whereas Foo() is a call.)
Alternatively, using a pattern plus word like for packages:
Match functions for hyperlinking:
[A-Z]\pL+\s+function
Match consts for hyperlinking:
[A-Z]\pL+\s+const
and similarly for vars and types.
--
Mark Summerfield, Qtrac Ltd, www.qtrac.eu
C++, Python, Qt, PyQt - training and consultancy
"Programming in Go" - ISBN 0321774639
http://www.qtrac.eu/gobook.html
Volker Dobler
> What is the problem you are trying to solve?
a) Headings to structure longer and complex documentation.
b) More structure in the generated html doc by use of
native list instead of verbatim/pre-formatted lists
which look like code: Clearer distinction between
"this is code, example, input, etc." and "this is
a list which explains stuff."
> We have deliberately avoided creating some kind of markup language for
> godoc comments. The current rule is: comments are either regular text or
> pre-formatted fixed-width text (signified via indent).
No markup (or markdown). Pre-formatted text stays (even inside a li
element).
> As for bullet elements and so on I don't see the additional complexity
> (both in writing and parsing) as worth it.
It is not that complex to parse and lists are already written to
look good and homogeneous as comment, see e.g.
http://golang.org/src/pkg/xml/read.go?#L90
http://tip.goneat.org/src/pkg/encoding/json/encode.go?#L45
http://tip.goneat.org/src/pkg/html/template/content.go#L13
The last example looks ugly if formatted as html due to the
missing indentation.
Adding/removing a handful of spaces could turn all these
lists into nice ol/ul lists. I think this little bit of
additional complexity would be worth the big benefit from a
better structured (in the sense of "pre-formated is code,
and lists are lists") html output.
Should I try to measure the additional time spent while
trying to parse lists?
Volker
Rob 'Commander' Pike
Besides the issues already raised, I notice that almost no code I see announced here uses the commenting style we prefer. Yesterday Miki Tebeka posted an App Engine demo, which was overall fine code but has stuff like this:
// Get current count of urls
func getCount(ctx appengine.Context) (int64, os.Error) {
// Get next id (short url). We use the global counter and then encode the last count in base62
func nextId(ctx appengine.Context) (string, os.Error) {
Inconsistent naming, doc comments that say what the function does instead of being a declarative sentence, incomplete punctuation, incorrect capitalization, "get", etc. That is, I'd rather see these as
// count returns the current count of URLs.
func count(ctx appengine.Context) (int64, os.Error) {
// nextId returns the next short URL id. It uses the global counter and encodes it in base62.
func nextId(ctx appengine.Context) (string, os.Error) {
And then, many packages have no godoc comments at all! Eleanor McHugh posted one of those a couple of days ago.
So, it's already too hard to get good documentation, and you're all arguing for making the comments harder to write by enforcing invisible stylistic rules for formatting.
I'd rather address the stuff that matters first.
-rob
Stetson
Markdown looks pretty simple to me, and it doesn't really look like
markup when you're looking at the raw text. There are already
apparently some invisible markup conventions for indentation. I would
think that using markdown, or at least parts of it, would add some
functionality without getting in the way like Javadoc.
Many of the ideas proposed in this thread, such as using markers for
lists (markdown recognizes *, +, or -) are already covered.
Even if markdown isn't implicitly used, I think it could serve as an
example for new formatting ideas.
Rodrigo Moraes
> So, it's already too hard to get good documentation, and you're all arguing for making the comments harder to write by enforcing invisible stylistic rules for formatting.
It is harder to write good documentation when you can't punctuate
narrative docs using headings. It is harder to read, too. This is the
main issue some of us are pointing.
No matter if there are some rules or no rules at all, some people will
always write bad docs, or no docs at all. But this is not a good
argument to avoid improving the documentation tools.
-- rodrigo
Rob 'Commander' Pike
-rob
Peter Bourgon
> narrative docs using headings. It is harder to read, too. This is the
> main issue some of us are pointing.
-1.
> No matter if there are some rules or no rules at all, some people will
> always write bad docs, or no docs at all. But this is not a good
> argument to avoid improving the documentation tools.
man pages and RFCs are consistently better documentation than info
pages and ITU-T specifications, respectively. I think this is in no
small part due to the formers' lack of superflous verbiage,
formatting, and (in other words) attention to things which ultimate
don't affect programmer comprehension and understanding. If the
standard library gets by with the current system -- and let's be
clear: it does -- then I see no compelling reasons, and potentially
severe and significant drawbacks, to "adding features" to this area.
Rodrigo Moraes
> If the
> standard library gets by with the current system -- and let's be
> clear: it does
I don't think it does. Narrative docs are terrible to read, with all
respect to the amount of effort put on this.
-- rodrigo
Volker Dobler
> So, it's already too hard to get good documentation, and you're
> all arguing for making the comments harder to write by enforcing
> invisible stylistic rules for formatting.
There are already "invisible stylistic rules" in place:
The doc generated for foo from
// ABC
//
// XYZ
func foo() {
and from
// ABC
// XYZ
func foo() {
is different and people do get trapped in this (at least once).
>
> I'd rather address the stuff that matters first.
>
Okay. Suggestions?
Please don't answer "Pick any issue with gc, cgo or gccgo".
I assume that once Go 1 is released it will be hard to
change godoc's interpretation of comments.
Volker
Rodrigo Moraes
1. Convert http://golang.org/doc/install.html to godoc.
2. Generate HTML.
3. See how bad godoc is at narrative documentation when used in web
and print.
(we don't need to go that far; see template package documentation or
others for examples of bad readability/scannability)
The proposal people here agreed with is not to add a lot of rules and
syntax and turn it into a javadoc, but to allow some extra
interpretation of blank lines and such things to generate more
appealing, easier to read (and write, I'd say from my little
experience writing go docs) narrative documentation.
-- rodrigo
Salman Aljammaz
> 1. Convert http://golang.org/doc/install.html to godoc.
> 2. Generate HTML.
> 3. See how bad godoc is at narrative documentation when used in web
> and print.
I think it makes sense godoc can't generate install.html; it's a tool
to document go code and APIs. It's not a generic document preparation
system. Use HTML, *roff, LaTeX, Markdown, DocBook, Google Docs, or
even MS Word if you want to write an extended structured document.
s
Rodrigo Moraes
> I think it makes sense godoc can't generate install.html; it's a tool
> to document go code and APIs. It's not a generic document preparation
> system. Use HTML, *roff, LaTeX, Markdown, DocBook, Google Docs,
That was a bad example to show how inappropriate it is for narrative
docs. The problem is that it is used for narrative documentation in
packages docs. See the output of http://golang.org/pkg/template/ or
http://golang.org/cmd/goinstall/ or many others -- it could be better.
As it is, the narrative is hard to scan, read and use as reference.
> or even MS Word if you want to write an extended structured document.
No need to go that low. ;)
-- rodrigo
Steve McCoy
Volker Dobler
On Nov 24, 2:28 am, Steve McCoy <mcco...@gmail.com> wrote:
> Man pages have section headings, though. I don't think wanting headings (at
> least) is equivalent to wanting full control over all formatting. Markdown
> was mentioned a couple times and I wouldn't want to see it either, but I
> don't think that Volker and Rodrigo are arguing for anything like that.
> On the other hand, I get Rob's point about documentation in the wild. If
> everybody's already writing crappy comments that don't follow the simple
> godoc style, I'd rather those at least look decent than be badly-written
> *and* formatted with a bunch of unintentional headings or whatever.
I hope that the headline detection is restrictive enough (it could be
made
even more restrictive by forcing captitalization) to not produce
unintentional
headings in badly documented code.
Not beeing able to use headings will not encourage people to write
proper comments but might discourage some of the ones willing to
do so.
Jan Mercl
Not beeing able to use headings will not encourage people to write
proper comments but might discourage some of the ones willing to
do so.
André Moraes
// Heading
//
//
// This is the body
Is much more simpler and nice to read.
If Headings will come into the godoc, I prefer the way Volkar's CL.
After all, what you suggested is just markdown.
Jan Mercl
I don't think that the extra markup for "=========" is really necessary.// Heading
//
//
// This is the bodyIs much more simpler and nice to read.
If Headings will come into the godoc, I prefer the way Volkar's CL.
After all, what you suggested is just markdown.
Bobby Powers
On Nov 23, 5:03 pm, Rob 'Commander' Pike <r...@google.com> wrote:> I'd rather address the stuff that matters first.Okay. Suggestions?
>
Please don't answer "Pick any issue with gc, cgo or gccgo".
André Moraes
> [example] usage of '======' (which makes them visible) is not really
> necessary" - what am I missing? ;-)
Just using the two spaces proposed by Voker will make the heading
visible both on unformated (godoc cli or source code) since we will have
a bigger paragraph describing de functionality, and on the html version
of the documentation which will generate <h3> tags.
The heading are intended to make easy to find some part of text in the middle
of a bigger prose. Using headers just to identify three lines of text
isn't a real
gain over the way things are now, that's why the extra markup, in my opinion,
isn't needed.
Jan Mercl
Just using the two spaces proposed by Voker will make the heading
visible both on unformated (godoc cli or source code) since we will have
a bigger paragraph describing de functionality, and on the html version
of the documentation which will generate <h3> tags.The heading are intended to make easy to find some part of text in the middle
of a bigger prose. Using headers just to identify three lines of text
isn't a real
gain over the way things are now, that's why the extra markup, in my opinion,
isn't needed.
André Moraes
From the last message that you sent, I didn't notice the identation on the left.
Your approach really solves the "heading" problem without changing godoc.
Sorry for the misunderstanding.
But since identation is used for defining pieces of source code, using the same
markup for different things might not be a good idea.
Jan Mercl
> standout in HTML, see: http://goo.gl/8WyhWFrom the last message that you sent, I didn't notice the identation on the left.
Your approach really solves the "heading" problem without changing godoc.Sorry for the misunderstanding.
But since identation is used for defining pieces of source code, using the same
markup for different things might not be a good idea.
Andrew Gerrand
On Wednesday, November 23, 2011 9:59:01 PM UTC+11, Volker Dobler wrote:
On Nov 23, 2:11 am, Andrew Gerrand <a....@golang.org> wrote:
> What is the problem you are trying to solve?a) Headings to structure longer and complex documentation.
b) More structure in the generated html doc by use of
native list instead of verbatim/pre-formatted lists
which look like code: Clearer distinction between
"this is code, example, input, etc." and "this is
a list which explains stuff."
Andrew Gerrand
On Wednesday, November 23, 2011 9:59:01 PM UTC+11, Volker Dobler wrote:
It is not that complex to parse and lists are already written to
look good and homogeneous as comment, see e.g.
http://golang.org/src/pkg/xml/read.go?#L90
http://tip.goneat.org/src/pkg/encoding/json/encode.go?#L45
http://tip.goneat.org/src/pkg/html/template/content.go#L13
The last example looks ugly if formatted as html due to the
missing indentation.
Adding/removing a handful of spaces could turn all these
lists into nice ol/ul lists. I think this little bit of
additional complexity would be worth the big benefit from a
better structured (in the sense of "pre-formated is code,
and lists are lists") html output.
DisposaBoy
Volker Dobler
On Nov 25, 1:19 am, Andrew Gerrand <a...@golang.org> wrote:
> On Wednesday, November 23, 2011 9:59:01 PM UTC+11, Volker Dobler wrote:
>
> > It is not that complex to parse and lists are already written to
> > look good and homogeneous as comment, see e.g.
> >http://golang.org/src/pkg/xml/read.go?#L90
> >http://tip.goneat.org/src/pkg/encoding/json/encode.go?#L45
> >http://tip.goneat.org/src/pkg/html/template/content.go#L13
> > The last example looks ugly if formatted as html due to the
> > missing indentation.
> > Adding/removing a handful of spaces could turn all these
> > lists into nice ol/ul lists. I think this little bit of
> > additional complexity would be worth the big benefit from a
> > better structured (in the sense of "pre-formated is code,
> > and lists are lists") html output.
>
> Do you intend to support each of the differing list styles represented by
> those three examples?
Yes, that was the idea; It is not that many and they are pretty much
similar. I was thinking of -, and * for bullet lists and 1. and A)
for enumerations. Adding e.g. o and (a) would be trivial but
I don't like style-proliferation.
> What about the others that you haven't thought of
> yet? Or will you require all lists to be written in a specific style? This
> is the complexity I'm referring to.
All the style I haven't thought of will be output as
preformatted text as it is done currently. So absolutely
no harm done here. No change required to any list.
Funny enough just a view ours ago a badly formatted enumeration
was naturally changed to one of the style supported:
http://groups.google.com/group/golang-dev/browse_thread/thread/bceb17e5caca79e
This happened (probably) because this style is a) natural and b)
looks good in source, and not because it would be formatted as
an ol in html.
> Are you aware of godoc/gotest's example code feature? It is not widely used
> yet, but you can see an example on the recent docs for sort.Ints:
> http://weekly.golang.org/pkg/sort/#Ints
I am, and it is perfect for code:
Giving examples often helps understanding the function/method
better and faster than long descriptive texts.
But IMHO it doesn't solve the "problem" of structuring longer
descriptions (which are uncommon for most methods, but do
occur as package or type docs).
Currently there are:
- Headings for types, functions, etc.,
- Text for description, and
- Preformatted text for anything else, especially code _and_ lists
For short descriptions this is perfectly fine, but I personally
would like to see descriptive lists visually different from code
simply because it make scanning the documentation faster.
That is the only reason why I argue to have:
- Headings
- Text for description,
- Preformatted text for anything else, and
- The optional possibility to write preformatted lists
which would be rendered as ol/ul.
Maybe my code would show clearer what it does and
what not. I could prepare a CL so anybody could just
test it and see if the list detection logic seems to
heavy-weight or to intrusive.
Volker
Jan Mercl
Volker Dobler
I think the case is completely different: If you make
kind of "syntax or formatting" error in a list there
won't be any error or misformatting or misinterpretation
of your comments. Your list just wont show up as ul/ol
in html but as pre or p just as it does now. Fine,
still production ready code and documentation.
And understanding the list formatting "rules" is
dead simple: Lists must look like
* foo
* bar
or
1. first
2. second
That's it.
And if your background is law and you write your lists as
§1 foo
§2 bar
or
i) first
ii) second
your list will show up as preformatted text and you
would be happy.
eaburns
Are you aware of godoc/gotest's example code feature? It is not widely used yet, but you can see an example on the recent docs for sort.Ints:
Andrew Gerrand
Andrew Gerrand
On Friday, November 25, 2011 8:21:49 PM UTC+11, Volker Dobler wrote:
Funny enough just a view ours ago a badly formatted enumeration
was naturally changed to one of the style supported:
http://groups.google.com/group/golang-dev/browse_thread/thread/bceb17e5caca79e
This happened (probably) because this style is a) natural and b)
looks good in source, and not because it would be formatted as
an ol in html.
Maybe my code would show clearer what it does and
what not. I could prepare a CL so anybody could just
test it and see if the list detection logic seems to
heavy-weight or to intrusive.