Hi,
TLDR:
#doc
## Let s use md formatting via a whole new token
in my doc __because__ in bold it is clearer it is important.
Please take care to
```go
useProperMdSyntax(ok)
``
# func mysuperFunc() {}
This email to talk about the documentation of go code,
and gocode.
Let me say first, i m very happy about the centralized documentation
offered by the go team.
The fact there is something that just works is great.
Now let s jump into stuffs i feel like not working properly,
1/ the way to document is not so obvious.
There are some documents about the way to go document,
but like template package, i found it difficult to find and read.
Maybe i missed some documents, let me know.
2/ The formatting is never as i expect.
See this example,
https://godoc.org/github.com/mh-cbon/gigo/interpreter/glang#GigoInterpreter.ReadAssignExpr
and its source
https://github.com/mh-cbon/gigo/blob/master/interpreter/glang/glang.go#L1493
The difference is huge. The result is deceiving.
It adds extra work on a activity we don t necessary all appreciates.
3/ The rules existing today are enforcing us in a way that is not practical.
If i take my previous example, the doc block was
// ReadAssignExpr reads a block of expressions.
// returns an error if none is found.
// The next token to analyze must be of type open,
// the block must end with a token of type close.
// In between data are read as a golang assign,
// a = x
// a, b = x
// a, b = x, u
So if i d like to make it nice in gocode, i should
uncomment, tab, comment again like this
// ReadAssignExpr reads a block of expressions.
// returns an error if none is found.
// The next token to analyze must be of type open,
// the block must end with a token of type close.
// In between data are read as a golang assign,
// a = x
// a, b = x
// a, b = x, u
It is not an impossible manipulation, yeah, I m stating that it is just not
friendly.
That would be friendlier,
/*
ReadAssignExpr reads a block of expressions.
returns an error if none is found.
The next token to analyze must be of type open,
the block must end with a token of type close.
In between data are read as a golang assign,
a = x
a, b = x
a, b = x, u
*/
Except the fact i feel like it is unusual to use block code to comments
such
expressions, it works better, it is more usable,
https://godoc.org/github.com/mh-cbon/gigo/interpreter/glang#GigoInterpreter.ReadBinaryExpressionBlock
But my formatting is still broken as it ignores new lines i inserted.
Also, the code block formatting is in fact a super poor way to present and
format an information.
4/ I lost the code split i made when i put them into different files.
I had split the code into different files to serve a purpose of separation
to help clarity (i tried to).
But that is not reflected into gocode, everything appear under one (super
long) page.
5/ Despite all, i always feel like i missed the "start here indication"
when i read a doc on gocode.
See my example package, there a nice constructor(yeay), which is a good
hint about where to start,
but that s it. After you got to find it yourself.
One could do an example method.
Personally i often felt like it worked weirdly,
i mean it is based on some rules which are not obvious.
Also i often make a cli around a lib, unfortunately main can t be an
example.
See this other example
https://github.com/mh-cbon/emd/blob/master/main_test.go
and its godoc,
https://godoc.org/github.com/mh-cbon/emd
Should gocode relate a method to its test ? Or try to,
for one who does UTesting, that d be great way to demonstrate the lib usage.
again one example,
https://godoc.org/github.com/mh-cbon/gigo/interpreter/glang#GigoInterpreter.ReadAssignExpr
https://github.com/mh-cbon/gigo/blob/master/interpreter/glang/glang_test.go#L779
6/ Finally, after all, one idea i d like to promote, please invent a new
documentation token.
The two documentations token we used are older than me, and i feel like
we might have better documentation inventing a whole new token that d take
advantages of nowadays practices.
How about ?
#doc
## Let s use md formatting
in my doc __becasue__ in bold it is clearer it is important.
Please take care to
```go
useProperMdSyntax(ok)
``
# func mysuperFunc()
--
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.
