Make documentation great again #151
Conversation
ligurio
force-pushed
the
ligurio/gh-123-documentation
branch
8 times, most recently
from
050b67b to
ed954d0
Compare
There was a problem hiding this comment.
Most of commits seems reasonable and are determined to improve used experience.
But when I try to validate it through godoc compiled version, it all seems inconvenient and broken in many ways. I've tried to ask @ligurio about how he had installed godoc, but he said that he used the same approach. My godoc is installed with golang-golang-x-tools
golang-golang-x-tools:
Installed: 1:0.0~git20191118.07fc4c7+ds-1
Candidate: 1:0.0~git20191118.07fc4c7+ds-1
Version table:
*** 1:0.0~git20191118.07fc4c7+ds-1 500
500 http://archive.ubuntu.com/ubuntu focal/universe amd64 Packages
100 /var/lib/dpkg/status
I provided several screenshots, so if they aren't similar to what any other reviewer or developer see, it should be clarified how to compile this documentation locally to verify what's going on.
My godoc compiled version missed any traces of README, so it isn't clear what this package is and how one should use it. Moreover, examples from README here https://pkg.go.dev/github.com/tarantool/go-tarantool#section-readme were more convenient to read that current godoc version. Again, it seems to me that it is more a godoc problem rather than this PR, but we should re-clarify this. Since README section is supported, I think it woudn't be bad to have a simple usage example in README: it is parsed both with pkg.go.dev and GitHub, so is easier for user to start (rather than lookup code files/code example trying to find where is the starting point).
This PR also uncovers one more issue: current doc is full of flaws. Some descriptions are vague, there are many grammar mistakes. It closes "Consider generation of API documentation from sources" issue, but should be followed by several more issues making current documentation really great.
I understand that many comment are really troublesome to implement now (like links in function descriptions) and it is better to left them to the next doc upgrade. But if some of them could be fixed within a reasonable period of time, it would be nice.
ligurio
force-pushed
the
ligurio/gh-123-documentation
branch
12 times, most recently
from
e602d2a to
7aa00f8
Compare
- make example executable - add description with steps how to run example manually Part of #123
ligurio
force-pushed
the
ligurio/gh-123-documentation
branch
from
00755db to
0e25a34
Compare
- make example executable with adding reference output - add description of steps how to run example manually - update comments for methods in queue.go See more about running examples in "Testable Examples in Go" [1] and testing package documentation [2]. Part of #123 1. https://go.dev/blog/examples 2. https://pkg.go.dev/testing#hdr-Examples
README contains an example like already exist in a example_test.go, so example in a README was removed and example in tests has been updated: - single example splitted to multiple examples for Connection methods - added new examples for Ping(), Insert(), Delete(), Replace(), Update(), Call17(), Eval() and Connect() Part of #123
Previously each example created a connection and processed error. To make examples more compact and clear for documentation reader patch handles connection error in example_connect() used in examples and panics in case of error. Part of #123
Make example executable by adding reference output to the comments. Part of #123
- split schema example to multiple examples - make examples executable Part of #123
- commented out code with old way to register types has been removed. - examples and tests shares common data structures and it's methods, so tarantool_test.go was updated as well to allow building a new example. Part of #123
Go 1.3 mentioned in installation section was EOLed many years ago. No sense to describe it's installation. Go 1.3 replaced with Go 1.13. Go 1.13 is outdated too and unsupported, but we run tests with it in Github Actions so it is a guarantee that everything will works with it. Part of #123
There is a guide made by Github with recommendations how to make project healthy for contributors [1]. One of them is a contributing guide with steps for new contributors. Knowledge about running tests in a project is not needed to all people who will read our README, so I moved this section to contributing guide. Part of #123 1. https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions
We have a walking through example in a README and examples in GoDoc. Seems it is more than enough. Part of #123
Part of #123
- add a section 'Documentation' and two subsections: - with 'Walking Through' example - with API documentation - fix code formatting in 'Walking-Through' example - remove description of Opts settings in description for 'Walking-Through' example - remove a program name in description for 'Walking-Through' example - update English grammar in description for 'Walking Through' example Part of #123
ligurio
force-pushed
the
ligurio/gh-123-documentation
branch
from
0e25a34 to
20c78db
Compare
What was done:
How-to evaluate GoDoc locally:
$ godoc -http=localhost:6060Note for reviewers:
Useful documentation
Closes #123