Docs, clean-ups

Author: jotaen

klog/app/cli/args/misc.go

@@ -13,6 +13,9 @@ type DiffArgs struct {
 	Diff bool `name:"diff" short:"d" help:"Show difference between actual and should-total time."`
 }
 
+// GetWarning returns a warning if the user applied entry-level filtering (partial
+// records) *and* requested to compute the should-total diff, as that may yield
+// nonsensical results.
 func (args *DiffArgs) GetWarning(filterArgs FilterArgs) service.UsageWarning {
 	if args.Diff && filterArgs.hasPartialRecordsWithShouldTotal {
 		return service.DiffEntryFilteringWarning

klog/app/cli/args/now.go

@@ -34,6 +34,8 @@ func (args *NowArgs) HadOpenRange() bool {
 	return args.hadOpenRange
 }
 
+// GetWarning warns the user that they specified the --now flag but there actually
+// weren’t any closable ranges in the data.
 func (args *NowArgs) GetWarning() service.UsageWarning {
 	if args.Now && !args.hadOpenRange {
 		return service.PointlessNowWarning

klog/app/cli/print.go

@@ -25,7 +25,7 @@ func (opt *Print) Help() string {
 Outputs data on the terminal, by default with syntax-highlighting turned on.
 Note that the output doesn’t resemble the file verbatim, but it may apply some minor formatting.
 
-If run with filter flags, it only outputs those entries that match the filter clauses (i.e., you may see partial records).
+If run with filter flags, it only outputs those entries that match the filter clauses. E.g., when filtering for a tag that only appears particular entries, it will exclude all other entries from that record.
 
 You can optionally also sort the records, or print out the total times for each record and entry.
 `

klog/app/config.go

@@ -245,7 +245,7 @@ var CONFIG_FILE_ENTRIES = []ConfigFileEntries[any]{
 				"`OVERLAPPING_RANGES` (for time ranges that overlap), " +
 				"`MORE_THAN_24H` (if there is a record with more than 24h total), " +
 				"`POINTLESS_NOW` (when using --now without any open ranges), " +
-				"`DIFF_ENTRY_FILTERING` (for combining --diff and entry-level filtering). " +
+				"`ENTRY_FILTERED_DIFFING` (when combining --diff and entry-level filtering). " +
 				"Multiple values must be separated by a comma, e.g.: `UNCLOSED_OPEN_RANGE, MORE_THAN_24H`.",
 			Default: "If absent/empty, klog prints all available warnings.",
 		},

klog/service/filter/filter.go

@@ -6,9 +6,9 @@ import (
 
 // Filter goes through a list of records and only keeps those that match the
 // given predicate. The records may be returned partially, keeping only those
-// entries that match the predicate. The second return value indicates whether
-// there are partial records with ShouldTotal set, as this may yield nonsensical
-// results in a subsequent evaluation.
+// entries that match the predicate.
+// The second return value indicates whether there are partial records with a
+// should-total set, as this may yield nonsensical results in a subsequent evaluation.
 func Filter(p Predicate, rs []klog.Record) ([]klog.Record, bool) {
 	var res []klog.Record
 	hasPartialRecordsWithShouldTotal := false

klog/service/filter/filter_test.go

@@ -11,6 +11,9 @@ import (
 
 func sampleRecordsForQuerying() []klog.Record {
 	rs, _, err := parser.NewSerialParser().Parse(`
+1999-12-29
+No tags here
+
 1999-12-30
 Hello World #foo #first
 
@@ -62,6 +65,7 @@ func TestQueryWithNoClauses(t *testing.T) {
 	rs, hprws := Filter(And{}, sampleRecordsForQuerying())
 	assert.False(t, hprws)
 	assertResult(t, []expect{
+		{klog.Ɀ_Date_(1999, 12, 29), []int{}},
 		{klog.Ɀ_Date_(1999, 12, 30), []int{}},
 		{klog.Ɀ_Date_(1999, 12, 31), []int{300}},
 		{klog.Ɀ_Date_(2000, 1, 1), []int{15, 360, -30}},
@@ -101,22 +105,13 @@ func TestQueryWithBefore(t *testing.T) {
 	}, sampleRecordsForQuerying())
 	assert.False(t, hprws)
 	assertResult(t, []expect{
+		{klog.Ɀ_Date_(1999, 12, 29), []int{}},
 		{klog.Ɀ_Date_(1999, 12, 30), []int{}},
 		{klog.Ɀ_Date_(1999, 12, 31), []int{300}},
 		{klog.Ɀ_Date_(2000, 1, 1), []int{15, 360, -30}},
 	}, rs)
 }
 
-func TestQueryWithTagOnEntries(t *testing.T) {
-	rs, hprws := Filter(HasTag{klog.NewTagOrPanic("bar", "")}, sampleRecordsForQuerying())
-	assert.True(t, hprws)
-	assertResult(t, []expect{
-		{klog.Ɀ_Date_(1999, 12, 31), []int{300}},
-		{klog.Ɀ_Date_(2000, 1, 1), []int{360}},
-		{klog.Ɀ_Date_(2000, 1, 3), []int{240, 180}},
-	}, rs)
-}
-
 func TestQueryWithTagOnOverallSummary(t *testing.T) {
 	rs, hprws := Filter(HasTag{klog.NewTagOrPanic("foo", "")}, sampleRecordsForQuerying())
 	assert.False(t, hprws)
@@ -128,6 +123,16 @@ func TestQueryWithTagOnOverallSummary(t *testing.T) {
 	}, rs)
 }
 
+func TestQueryWithTagOnEntries(t *testing.T) {
+	rs, hprws := Filter(HasTag{klog.NewTagOrPanic("bar", "")}, sampleRecordsForQuerying())
+	assert.True(t, hprws)
+	assertResult(t, []expect{
+		{klog.Ɀ_Date_(1999, 12, 31), []int{300}},
+		{klog.Ɀ_Date_(2000, 1, 1), []int{360}},
+		{klog.Ɀ_Date_(2000, 1, 3), []int{240, 180}},
+	}, rs)
+}
+
 func TestQueryWithTagOnEntriesAndInSummary(t *testing.T) {
 	rs, hprws := Filter(And{[]Predicate{HasTag{klog.NewTagOrPanic("foo", "")}, HasTag{klog.NewTagOrPanic("bar", "")}}}, sampleRecordsForQuerying())
 	assert.True(t, hprws)

klog/service/warning.go

@@ -19,7 +19,7 @@ var (
 		Message: "You specified --now, but there was no open-ended time range",
 	}
 	DiffEntryFilteringWarning = UsageWarning{
-		Name:    "DIFF_ENTRY_FILTERING",
+		Name:    "ENTRY_FILTERED_DIFFING",
 		Message: "Combining --diff and filtering at entry-level may yield nonsensical results",
 	}
 )