General improvements to the documentation #375
Conversation
|
One thing I'm not too happy about right now is that Gradle is enforcing checkstyle on the examples, which is nice in theory but it causes some lines to wrap in inconvenient ways... not sure if we should reformat or just turn it off? |
Is there a specific example of this? You can add a suppression to <suppress checks="LineLength" files="examples[\\/].*"/> |
It's mostly in the method signatures of things where checkstyle seems to want parameters to be final, e.g.: public static void handleEvent(final LongEvent event, final long sequence, final boolean endOfBatch)Because of the formatting, this ends up rendered in the HTML as: public static void handleEvent(final LongEvent event, final long sequence, final boolean
endOfBatch) |
|
Feels like what you want is checkstyle to have a smaller |
Previously, the example code was all written directly into the documentation, decoupling it from any real code. This meant changes to APIs or whatever could unknowningly break the example code, adding to the number of considerations that a developer would, in theory, be required to worry about when changing something. By promoting these examples to real code, we can offload that mental strain onto the compiler, thus giving us more confidence that the examples work. In theory, it also means that in the future we could even add some tests for these to prove they're doing what we claim!
Specifically:
- move the Java 8 examples to the top, as using these features is likely
to be more common than using the legacy styles
- replace in-example comments with callouts for better readability
- general rewording to make it easier to read
This will fix some grammar warnings and shuffle some paragraphs around.
A PR for general improvements to the documentation.
So far: