"Comprehensive documentation" has missing sections

Open
#199 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
clojure
Domain
documentation

Research direction

Start by locating the Tick documentation sections listed in the issue, especially sections 4.6 through 10.9, and review the existing Tick Reference entries. Inventory missing text, TODOs, unclear API explanations, and outdated references before proposing a scope. Done means the selected sections are complete, consistent with Tick 1.0, and the documented API is up to date.

Written by the indexing model from the issue text.

Description

help wanted

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.
Dominant language
Clojure
Stars
646
Forks
61
Avg merge
17h 42m
Merged PRs (30d)
1

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from juxt/tick

All issues in juxt/tick

Similar issues

More Clojure issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.