Consider generation of API documentation from sources #123

Totktonada · 2021-12-13T07:52:07Z

Filed here to collect opinions. Sometimes it is convenient to support API documentation in the form of annotations right within the code. Sometimes, actually, not.

I guess if we'll go with deployments to pkg.go.dev (in #121), we'll need documentation in some standard format and maybe we'll imposed to generate it from sources.

For me it is terra incornita now: need to investigate the topic and collect opinions from experienced Go developers.

If we'll go this way, I assume a considerable amount of work to actually write the annotations as part of this issue.

Added examples of using SQL queries in example_test.go for compiling the future documentation from sources. Follows up #62 Relates to #123

Badge was added in commit "Add info to README" (eb82a68) and was commented out from the beginning. We don't use Travis CI, so it was removed. Part of #123

Add GoDoc bagde generated by [1] with link to HTML documentation, badge for GH Actions, badges for Telegram channel, StackOverflow topic and Github Discussions. Part of #123 1. https://pkg.go.dev/badge/

- replace "tarantool" with "Tarantool" - replace "lua" with "Lua" - remove apostrophes in comments - fixed typos - remove unneeded empty lines that break documentation generation - add a version where new methods or packages were added - remove apostrophes in comment for Connection - add dots to the end of sentences - start sentences with capitalized letter Part of #123

- make example executable - add description with steps how to run example manually Part of #123

- 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. Part of #123

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

Part of #123

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

Part of #123

Closes #123

After PR #151 Go requirement in README was bumped to version 1.13. But README still contains a line describing version 1.3. This patch fixes it. Follows up #123

Follows up #123

After PR #151 Go requirement in README was bumped to version 1.13. But README still contains a line describing version 1.3. This patch fixes it. Follows up #123

Follows up #123

Added examples of using SQL queries in example_test.go for compiling the future documentation from sources. Follows up #62 Relates to #123

Follows up tarantool/go-tarantool#142 Follows up tarantool/go-tarantool#123

…nalysis) (#2860) * Update go-tarantool in comparison table Follows up tarantool/go-tarantool#142 Follows up tarantool/go-tarantool#123 * Update translation Co-authored-by: Patience Daur <[email protected]>

Overview This release adds a number of features and updates documentation. Breaking changes There are no breaking changes in the release. New features Coveralls support (#149). Reusable testing workflow (integration testing with latest Tarantool) (#123). Simple CI based on GitHub actions (#114). Support UUID type in msgpack (#90). Go modules support (#91). queue-utube handling (#85). Master discovery (#113). SQL support (#62). Handle everything with `go test` (#115). Update API documentation: comments and examples (#123). Bugfixes Reset buffer if its average use size smaller than quater of capacity (#95). Fix queue tests (#107). Make test case consistent with comments (#105).

Overview This release adds a number of features and updates documentation. Breaking changes There are no breaking changes in the release. New features Coveralls support (#149). Reusable testing workflow (integration testing with latest Tarantool) (#112). Simple CI based on GitHub actions (#114). Support UUID type in msgpack (#90). Go modules support (#91). queue-utube handling (#85). Master discovery (#113). SQL support (#62). Handle everything with `go test` (#115). Update API documentation: comments and examples (#123). Bugfixes Reset buffer if its average use size smaller than quater of capacity (#95). Fix queue tests (#107). Make test case consistent with comments (#105).

Overview This release adds a number of features. Also it significantly improves testing, CI and documentation. Breaking changes There are no breaking changes in the release. New features Support UUID type in msgpack (#90). queue-utube handling (#85). Master discovery (#113). SQL support (#62). Bugfixes Reset buffer if its average use size smaller than quater of capacity (#95). Testing Coveralls support (#149). Reusable testing workflow (integration testing with latest Tarantool) (#112). Simple CI based on GitHub actions (#114). Handle everything with `go test` (#115). Fix queue tests (#107). Make test case consistent with comments (#105). Other Go modules support (#91). Update API documentation: comments and examples (#123).

Closes #123

1. Closes #123

Totktonada added teamE code health Improve code readability, simplify maintenance and so on raw idea labels Dec 13, 2021

Totktonada assigned ligurio Feb 24, 2022

ligurio removed the raw idea label Mar 30, 2022

This was referenced Mar 31, 2022

Make documentation great again #151

Merged

Add minimal sql support #144

Merged

vr009 added a commit that referenced this issue Apr 4, 2022

readme: add examples of usage SQL in connector

70fd650

Added examples of using SQL queries in example_test.go for compiling the future documentation from sources. Follows up #62 Relates to #123

vr009 added a commit that referenced this issue Apr 4, 2022

readme: add examples of usage SQL in connector

7b03637

Added examples of using SQL queries in example_test.go for compiling the future documentation from sources. Follows up #62 Relates to #123

vr009 added a commit that referenced this issue Apr 4, 2022

readme: add examples of usage SQL in connector

6249bdd

Added examples of using SQL queries in example_test.go for compiling the future documentation from sources. Follows up #62 Relates to #123

vr009 added a commit that referenced this issue Apr 11, 2022

readme: add examples of usage SQL in connector

ed46345

Added examples of using SQL queries in example_test.go for compiling the future documentation from sources. Follows up #62 Relates to #123

vr009 added a commit that referenced this issue Apr 13, 2022

readme: add examples of usage SQL in connector

8c5083d

Added examples of using SQL queries in example_test.go for compiling the future documentation from sources. Follows up #62 Relates to #123

ligurio added a commit that referenced this issue Apr 14, 2022

readme: remove commented out travis-ci badge

a2d1a91

Badge was added in commit "Add info to README" (eb82a68) and was commented out from the beginning. We don't use Travis CI, so it was removed. Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

queue: make example executable

8b1bd33

- make example executable - add description with steps how to run example manually Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

readme: move uuid example to tests

0f2ad63

Make example executable by adding reference output to the comments. Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

readme: move schema example to tests

613127d

- split schema example to multiple examples - make examples executable Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

readme: move custom unpacking example to tests

063ff8d

Commented out code with old way to register types has been removed. Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

readme: move description of options to inline comment

3e084d4

Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

readme: move description of multiple connections to comment

a44b50d

Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

multi: add documentation comments

200dc9d

Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

multi: add examples for connect functions

401d639

Part of #123

ligurio added a commit that referenced this issue Apr 14, 2022

readme: update section about testing

08eedb6

Part of #123

ligurio added a commit that referenced this issue Apr 20, 2022

readme: update section about API reference

7706f03

Part of #123

ligurio added a commit that referenced this issue Apr 20, 2022

readme: remove hello world example

9845962

We have a walking through example in a README and examples in GoDoc. Seems it is more than enough. Part of #123

ligurio added a commit that referenced this issue Apr 20, 2022

readme: remove help section

d206a85

Part of #123

ligurio added a commit that referenced this issue Apr 20, 2022

readme: update section about alternative connectors

6e9f65e

Part of #123

ligurio added a commit that referenced this issue Apr 20, 2022

changelog: add entry about updated documentation

fa856fc

Closes #123

DifferentialOrange added a commit that referenced this issue Apr 21, 2022

readme: make Go versions consistent

01c2fa0

After PR #151 Go requirement in README was bumped to version 1.13. But README still contains a line describing version 1.3. This patch fixes it. Follows up #123

DifferentialOrange mentioned this issue Apr 21, 2022

readme: make Go versions consistent #168

Merged

1 task

ligurio added a commit that referenced this issue Apr 21, 2022

readme: fix broken links

416c647

Follows up #123

ligurio added a commit that referenced this issue Apr 21, 2022

readme: use an existed link shortcut to godoc

0fd8f49

Follows up #123

ligurio mentioned this issue Apr 21, 2022

README fixes #169

Merged

DifferentialOrange added a commit that referenced this issue Apr 21, 2022

readme: make Go versions consistent

dd4f88f

After PR #151 Go requirement in README was bumped to version 1.13. But README still contains a line describing version 1.3. This patch fixes it. Follows up #123

ligurio added a commit that referenced this issue Apr 21, 2022

readme: fix broken links

dff20b3

Follows up #123

ligurio added a commit that referenced this issue Apr 21, 2022

readme: use an existed link shortcut to godoc

cb9f156

Follows up #123

vr009 added a commit that referenced this issue Apr 22, 2022

readme: add examples of usage SQL in connector

5f6571a

Added examples of using SQL queries in example_test.go for compiling the future documentation from sources. Follows up #62 Relates to #123

ligurio added a commit to tarantool/doc that referenced this issue May 6, 2022

Update go-tarantool in comparison table

99b002c

Follows up tarantool/go-tarantool#142 Follows up tarantool/go-tarantool#123

ligurio mentioned this issue May 6, 2022

Update go-tarantool in comparison table (code coverage, doc, static analysis) tarantool/doc#2860

Merged

ligurio added a commit to tarantool/doc that referenced this issue May 11, 2022

Update go-tarantool in comparison table

87c3819

Follows up tarantool/go-tarantool#142 Follows up tarantool/go-tarantool#123

ligurio added a commit to tarantool/doc that referenced this issue May 11, 2022

Update go-tarantool in comparison table

cb61c26

Follows up tarantool/go-tarantool#142 Follows up tarantool/go-tarantool#123

patiencedaur pushed a commit to tarantool/doc that referenced this issue May 16, 2022

Update go-tarantool in comparison table

c031bc9

Follows up tarantool/go-tarantool#142 Follows up tarantool/go-tarantool#123

oleg-jukovec mentioned this issue Jun 1, 2022

Release 1.6.0 #182

Merged

oleg-jukovec added a commit that referenced this issue Dec 25, 2022

api: remove multi subpackage

24e46ea

Closes #123

oleg-jukovec added a commit that referenced this issue Dec 25, 2022

api: rename connection_pool to pool

233ec5f

1. Closes #123

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consider generation of API documentation from sources #123

Consider generation of API documentation from sources #123

Totktonada commented Dec 13, 2021 •

edited

Loading

Consider generation of API documentation from sources #123

Consider generation of API documentation from sources #123

Comments

Totktonada commented Dec 13, 2021 • edited Loading

Totktonada commented Dec 13, 2021 •

edited

Loading