[COLLECTIONS-857] Update bloom filter documentation

[Claudenw]

This change continues the work on COLLECTIONS-857.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.45%. Comparing base (229425c) to head (6c45535).
Report is 315 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #508      +/-   ##
============================================
- Coverage     81.60%   81.45%   -0.16%     
- Complexity     4745     4834      +89     
============================================
  Files           295      300       +5     
  Lines         13751    14093     +342     
  Branches       2022     2071      +49     
============================================
+ Hits          11222    11479     +257     
- Misses         1929     1998      +69     
- Partials        600      616      +16     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[garydgregory]

Hi @Claudenw

Thank you for your PR.

Is there a reason we are documenting the feature in two places: In Javadoc and separate site pages? Why does some information go in one place vs. the other?

I always find that the "truth" is usually closest to the code and most likely to be maintained when near that code.

Also, note that starting with Java 18, we have the snippets Javadoc feature. So I think that long term, all docs should (IMO) go in Javadocs.

I don't know what happens if you plainly try to use snippets in Javadoc 8...

[Claudenw]

I think that there are two different audiences. Within the javadoc you have people that are looking for how the object does a specific thing. This audience is, mostly, already acquainted with the project and looking for specific information. The other documentation is for people who are not familiar with the code base. This documentation has a different focus, explaining how to use the project and how to think about using it. It is more of an introduction to what the project can do and perhaps toeing up to the marketing line. So javadoc should tell you things like argument "A" can not be null, or the return is never null, and perhaps what characteristics of the data are assumed by the implemented algorithm; low level technical stuff. The non javadoc can introduce usages of the code for example Bloom filter documentation talks about counting filters to solve removal of filter issues, and possible solutions for streaming data or indexing collections of filters; higher level technical thoughts. These sorts of things could be published in personal blogs and the like, but I think that putting it in the project documentation provides a better sense of permanence and correctness. Just my view, I hope it makes sense, Claude

…

On Mon, Jun 24, 2024 at 2:27 PM Gary Gregory ***@***.***> wrote: Hi @Claudenw <https://github.com/Claudenw> Thank you for your PR. Is there a reason we are documenting the feature in two places: In Javadoc and separate site pages? Why does some information go in one place vs. the other? I always find that the "truth" is usually closest to the code and most likely to be maintained when near that code. Also, note that starting with Java 18, we have the *snippets* Javadoc feature <https://blogs.oracle.com/javamagazine/post/java-javadoc-snippet>. So I think that long term, all docs *should* (IMO) go in Javadocs. I don't know what happens if you plainly try to use snippets in Javadoc 8... — Reply to this email directly, view it on GitHub <#508 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AASTVHV52YLG26VDQBSPNUTZJAGEPAVCNFSM6AAAAABJZWPFJSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCOBWGQ3DGNJQGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- LinkedIn: http://www.linkedin.com/in/claudewarren