"Comprehensive documentation" has missing sections

[dgr]

Now that Tick has been bumped to version 1.0, it seems like it would be good to finish out the documentation.

Notably, these sections need some love:

• 4.6 Comparison - no text
• 4.7 Modification - no text
• 4.8 Truncation - no text
• 5.2 Derivation - has a bullet about adding durations to durations, but no examples or other guidance
• 5.3 Comparison - seems pretty short, but might be OK. Appears that <= got converted to a left-facing arrow
• 5.4 Misc - has "TODO" markers
• 6.2 Derivation - makes the statement "Just like times and dates, you can time-shift clocks forward and backward using the >> and << functions respectively," but this is the first time that << and >> have been mentioned in the document.
• 6.3 Mutable Clocks - needs work. In section 6.0 the document says, "In tick, clocks are used for getting the current time, in a given time-zone. You should prefer using clocks to making direct calls to (System/currentTimeMillis), because this then allows you and others to plugin alternative clocks, perhaps for testing purposes," but then in 6.3 it says "Tick does not provide that because there is already Mock Clock," which is confusing. Does Tick want to solve this problem or not? If not, what's the purpose of Tick's Clock support?
• 6.4 Comparison - no text
• 6.5 Atomic Clocks? - Why the "?" in the section title? That said, it's not clear why this functionality exists and this isn't really explained in the text. Is there no other way to get the value out of a clock other than having it be storied in a special Tick atom? Why does it have to be stored in an atom instead of just calling a function (perhaps deref/@) on the clock itself? Is there some sort of atomicity guarantee that a Tick atom brings to the party? If so, what is it? Since clocks are just read (shifting a clock creates another clock, right?), then what is the point of having the atom? If I want a clock in an atom, can't I just store a clock in a regular Clojure atom?
• 6.6 Substitution - So, t/with-clock allows you to set the default clock for all the other Tick functions? If so, perhaps say that explicitly. What set of functions does it apply to and which not?
• 7 Intervals - are intervals still alpha given that Tick is version 1.0? Does the namespace need to be updated to remove the alpha part of the name? If this has already been done, then the documentation needs to be updated to reflect it. If there is more to do on intervals, what is missing and what timeframe is it targeted for? Something that remains in "alpha" state for a long time makes the project feel like it's been abandoned (sometimes Clojure Spec feels the same way for the same reason). Since intervals seem to be some of Tick's primary value-add beyond the raw time primitives provides by cljc-time, it would be good to have them be solid and finished, not in some quasi 1.0-by-still-alpha state.
• 7.4 Collections - seems like it wants to discuss something interesting but just doesn't complete the thought.
• 7.5 Demonstration - no text
• 8.0 - no text
• 8.1 - no text
• 8.2 - no text
• 8.3 - no text
• 9.0 - seems incomplete
• 10.8 Miscellaneous - need to find a home for these examples
• 10.9 Tick Reference - this section is great and helpful, but it feels like perhaps it could be replaced by another automated system (e.g., Codox). This wouldn't show the live examples, which are useful and that would be a loss, but it would make sure that all the API functions were listed and up to date. E.g., right now, I think it's missing min-key and max-key, right? There may be others, but I noticed those. Perhaps just adding those would be easiest for now.

[henryw374]

thanks @dgr for a comprehensive look at what needs to be done for tick docs. there's a lot to be done there, so any help appreciated.

re: section 6, clocks section.

• t/with-clock will change the behaviour of any function that would get a current date or time.
• the t/clock function returns a clock fixed in time and place. I think mutable clock is one that you can change in place. A more flexible and pure clojure alternative would be e.g. https://gist.github.com/henryw374/38d61b20c62cd5450331f36ee9029a61
• atomic clocks is not a feature I have used. you're right the ? should go

re Intervals - alpha status covered in the readme. should be in docs as well.