Discussion: use rustdoc for blocks' documentation

[MaxVerevkin]

In-code documentation is just easier to maintain.

The question is whether it is actually convenient for users. Here is an example of documentation (time block): https://maxverevkin.github.io/i3status-rust/doc/i3status_rs/blocks/time/index.html

[ammgws]

I like the idea of increasing maintainability but going with rustdoc it ends up being a bit overwhelming for standard users. Is there a rustdoc option to hide all the struct declarations and such?

[MaxVerevkin]

Unfortunately, I don't think there in an option to hide trait impls (it is possible to hide struct declarations).

I can imagine that if there was an option to output markdown, it would be easy to make the documentation cleaner for users.

From rust-lang/rust#44136 I understand that there were plans to support other output formats but it will never be implemented.

[MaxVerevkin]

Even though per-field documentation is not user-friendly, just writing all block related documentation in the beginning of source code is both convenient to maintain (better than having one huge .md file) and user friendly (is it?):

[ammgws]

Actually that might not be too bad!

[ammgws]

Should we go ahead and do it?

[MaxVerevkin]

@ammgws If you like how https://maxverevkin.github.io/swaystatus/docs/swaystatus/blocks/index.html looks then I suppose.

[ammgws]

It's grown on me

[jyn514]

From rust-lang/rust#44136 I understand that there were plans to support other output formats but it will never be implemented.

That issue was out of date, I updated it - there's an unstable JSON output format on nightly :) rust-lang/rust#76578

[ammgws]

@MaxVerevkin Do the docs have to be checked into the repo like at swaystatus for this to be usable online?

[MaxVerevkin]

I think so, unless we publish the crate on crates.io

[ammgws]

Do others publish programs to crates.io? I always thought it was for libraries that other crates can then import. Wonder if there's another way..

[MaxVerevkin]

Well, there are ripgrep, alacritty and zbus_xmlgen, but... it looks like docs are not generated for binary crates 😞