meilisearch/MeiliSearch

Major lack of documentation in codebase

Aperta

#3206 aperta il 7 dic 2022

 (6 commenti) (2 reazioni) (0 assegnatari)Rust (2542 fork)batch import
contribution accepteddocumentationgood first issue

Metriche repository

Star
 (57.572 stelle)
Metriche merge PR
 (Merge medio 11g 20h) (41 PR mergiate in 30 g)

Descrizione

Describe the bug The codebase significantly lacks documentation. As a newly introduced developer, it makes it hard for me to navigate the codebase and quickly identify which item does what. The documentation is needed as a source of intuition for evaluating whether some code item is valuable for the end-user, and whether it should be modified, and how exactly it should be modified to accomplish the desired behavior.

Without the said documentation, the codebase can easily become a jungle of functions/structs/enums/traits whose names only suffice for achieving a ballpark of correct understanding rather than the exact understanding required to modify the correct code in the correct way.

Documenting the codebase may constitute a significant upfront investment, but I believe it will pay off in the long run.

To Reproduce Steps to reproduce the behavior: cargo doc --open --document-private-items Alternatively, just look in the code on any arbitrary function/struct/impl/trait/etc. This problem seems to be pervasive throughout most of the codebase.

Expected behavior Each code item (struct, impl, trait, enum, function) should have documentation that explains how the given code item relates to the greater context from the end-user's point of view.

Guida contributor