"Comprehensive documentation" has missing sections

オープン
#199 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
25/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
clojure
領域
documentation

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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.
主要言語
Clojure
スター
646
フォーク
61
平均マージ
17時間 42分
マージ済み PR(30日)
1

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

juxt/tick のほかの issue

juxt/tick の issue をすべて見る

似ている issue

Clojure の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。