Rename sbot module and improve documentation #27

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

shorten module descriptions (remove 'golgi') 623d2d2260

add features and extend example usage section 518f2cbb12

refine overview docs and copy to readme 5cd2cae3ef

rename sbot dir to api f40cc793f0

move main sbot type definition to top-level ebb92aba24

add docs for each api module de6689220e

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

shorten doc comment line lengths b6fd2e2da5

update use paths d9839f1d06

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

add handshake error text 81e329b40e

revert connect fn to init d2a0c38f68

silly me; revert to 7aa32e24c7

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

remove notes which were accidentally committed 1c434193eb

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

clarify api descriptions for about msgs 9c959346f1

update kuska path and readme e0de8ec0d9

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

add an example for each about method 6d2115607b

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

add doc comment examples for friends api 635ebb2a8c

add doc comment examples for get_subset api 29d1927104

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

add doc comment examples for history api b714bda988

add doc comment examples for invite api d0f68086a1

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

add doc comment examples for publish api 1bb9e1f7e1

add doc comment examples for whoami api 32bd924e7e

polish the message type docs 8466510fee

polish the utility function docs 74b87b904b

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

use full path for pin_mut macro 506ebec7e4

extend documentation for all examples 6a1aa0abda

rename example files d4263b967f

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.