search

pchampin / sophia_rs

Sophia: a Rust toolkit for RDF and Linked Data
Other
214 stars 23 forks source link

Ensure doc coverage using #![deny(missing_docs)] #44

Closed MattesWhite closed 8 months ago

MattesWhite commented 4 years ago

#![deny(missing_docs)] is a macro that can be placed in any module. Using it results in compiler errors if a public element is not documented (///).

While this might lead to a number of 'obvious' documentations it is still a good measure to ensure a thorough documentation of the whole crate. In addition, it forces the developer to think about the users point of few on an element.

Solving this issue consists in adding #![deny(missing_docs)] incrementally to each and every module, until all are documented. Then, we can keep only one directive at the top-level (lib.rs).

pchampin commented 4 years ago

I'm all for it, but this will take some time to please this macro:

error: aborting due to 256 previous errors

:-/

MattesWhite commented 4 years ago

I found out that the macro #![deny(missing_docs)] can not only be applied to the whole library but also to (sub-)modules. Meaning the documentation effort can be progressed iteratively.

Therefore, I propose to mark this issue 'help_wanted' and 'good_first_issue'.

lulu-berlin commented 4 years ago

I took a stab at adding doc comments: https://github.com/pchampin/sophia_rs/pull/84

pchampin commented 8 months ago

fixed by 0c38774