Rustdocs Usage

[hemangandhi]

I was wondering if rustdoc was useful for this project (more or less fiddling to get maximal mileage out of rust's tooling).

Particularly, I have a small experiment in a fork. I was wondering if getting the rest of the README into such a format would be reasonable. I think there are a few advantages:

• Using doctests instead of #[test] keeps the source in one place and automatically ensures consistency.
• The site has a lot of internal linking that could become extremely useful. Especially with the search features.
• Would make for a nice github.io page (we'd need an index.html to link into the docs and not ignore target/docs).

This seems to have a few drawbacks:

• Everything becoming a doc-comment (/// with md formatting) might make linting and editing harder.
• Calling things modules and having stub functions is clumsy and prone to cause disagreements.
• The way doctests are handled is complicated and might make editing harder for beginners.

If this is interesting, I've also experimented on the azure pipeline, so was wondering how to test that?

[JasonShin]

Thanks =) I will try this out soon

[JasonShin]

Let me play around in your fork. It's an interesting idea

[hemangandhi]

https://github.com/hemangandhi/functional-programming-jargon.rs/blob/doctest/DOCTEST_TODO.md

^ this is my vision so far, though I definitely don't expect the last goal to happen/get merged in any time soon.

[JasonShin]

@hemangandhi Great ideas! I love it. I can work on the linting issues tonight. I was actually checking out how to enable RustDoc the other day according to your example folk but I got confused ... ;)...

Also, if you are interested in turning this into an actual module, let's do this in a separate project. Come and join us on telegram =) https://t.me/joinchat/Hj2nWg58UEWmMFprHvs-iQ

[JasonShin]

We have half solved this issue because now we have a documentation automatically generated on crates.io

https://docs.rs/fp-core/0.1.8/fp_core/