Rename sbot module and improve documentation #27

glyph · 2022-02-08T10:05:20Z

glyph commented

2022-02-08 10:05:20 +00:00

This PR renames the src/sbot module to src/api and moves the whoami method into a separate module (src/api/whoami.rs). This means that src/sbot.rs contains the Sbot struct and connection methods, while all other implemented methods are located in the src/api module.

While working on this PR, I rendered the documentation (cargo doc --open --no-deps) and used that as my primary means of evaluating the clarity of crate organisation and documentation. My goal was to make it as easy as possible for a potential golgi user to navigate and use the library by only looking at the generated Rust docs.

Each API module contains a list of implemented methods with a link to the detailed docs for each one (see the screenshot below for an example). I think this provides a neat way to get an overview of the available features without having to go straight to the Sbot docs page and search through all the methods.

API-specific types from kuska are exported through the relevant API modules. For example, the subset types:

use golgi::api::get_subset::{SubsetQuery, SubsetQueryOptions};

The main Sbot type and error type are exported at the top-level:

use golgi::{Sbot, GolgiError};

This PR renames the `src/sbot` module to `src/api` and moves the `whoami` method into a separate module (`src/api/whoami.rs`). This means that `src/sbot.rs` contains the `Sbot` `struct` and connection methods, while all other implemented methods are located in the `src/api` module. While working on this PR, I rendered the documentation (`cargo doc --open --no-deps`) and used that as my primary means of evaluating the clarity of crate organisation and documentation. My goal was to make it as easy as possible for a potential `golgi` user to navigate and use the library by only looking at the generated Rust docs. Each API module contains a list of implemented methods with a link to the detailed docs for each one (see the screenshot below for an example). I think this provides a neat way to get an overview of the available features without having to go straight to the `Sbot` docs page and search through all the methods. API-specific types from `kuska` are exported through the relevant API modules. For example, the subset types: ```rust use golgi::api::get_subset::{SubsetQuery, SubsetQueryOptions}; ``` The main `Sbot` type and error type are exported at the top-level: ```rust use golgi::{Sbot, GolgiError}; ```

DeepinScreenshot_select-area_20220208120130.png

56 KiB

glyph added 9 commits 2022-02-08 10:05:20 +00:00

623d2d2260 shorten module descriptions (remove 'golgi')

518f2cbb12 add features and extend example usage section

5cd2cae3ef refine overview docs and copy to readme

f40cc793f0 rename sbot dir to api

ebb92aba24 move main sbot type definition to top-level

de6689220e add docs for each api module

5bcdbfa7bd export Sbot as top-level and make api module public

b6fd2e2da5 shorten doc comment line lengths

d9839f1d06 update use paths

glyph added 3 commits 2022-02-08 13:05:06 +00:00

81e329b40e add handshake error text

d2a0c38f68 revert connect fn to init

7aa32e24c7 silly me; revert to

notplants commented

2022-02-08 18:06:36 +00:00

hey @glyph, I'm back online now, but still not with great work conditions.

cool to see this coming together :=)

hey @glyph, I'm back online now, but still not with great work conditions. cool to see this coming together :=)

❤️ 1

glyph added 1 commit 2022-02-09 06:55:27 +00:00

1c434193eb remove notes which were accidentally committed

glyph added 2 commits 2022-02-14 10:23:48 +00:00

9c959346f1 clarify api descriptions for about msgs

e0de8ec0d9 update kuska path and readme

glyph added 1 commit 2022-02-14 12:31:42 +00:00

6d2115607b add an example for each about method

glyph added 2 commits 2022-02-14 13:52:49 +00:00

635ebb2a8c add doc comment examples for friends api

29d1927104 add doc comment examples for get_subset api

glyph added 2 commits 2022-02-14 14:13:38 +00:00

b714bda988 add doc comment examples for history api

d0f68086a1 add doc comment examples for invite api

glyph added 4 commits 2022-02-14 15:00:21 +00:00

1bb9e1f7e1 add doc comment examples for publish api

32bd924e7e add doc comment examples for whoami api

8466510fee polish the message type docs

74b87b904b polish the utility function docs

glyph added 3 commits 2022-02-15 08:27:54 +00:00

506ebec7e4 use full path for pin_mut macro

6a1aa0abda extend documentation for all examples

d4263b967f rename example files

glyph commented

2022-02-15 08:34:08 +00:00

Lots of additional commits in the past two days.

I've added a working example for every method in the API. Really pleased with this approach!

I have found the The rustdoc book to be a handy resource (I'd somehow never read it before).

I've also added relatively extensive comments to each one of the examples (and I've renamed them to remove the ssb- portion in each filename).

Lots of additional commits in the past two days. I've added a working example for every method in the API. Really pleased with this approach! I have found the [The rustdoc book](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html) to be a handy resource (I'd somehow never read it before). I've also added relatively extensive comments to each one of the examples (and I've renamed them to remove the `ssb-` portion in each filename).

glyph merged commit 5099b56ecb into main

2022-02-15 08:34:51 +00:00

glyph deleted branch docs_review

2022-02-15 08:34:52 +00:00

glyph referenced this issue from a commit

2022-02-15 08:34:52 +00:00

Merge pull request 'Rename sbot module and improve documentation' (#27) from docs_review into main

glyph referenced this pull request

2022-02-15 13:01:48 +00:00

Improve doc comment coverage and detail #25

Sign in to join this conversation.

No reviewers