WIP: Update docstrings, comments, and readme

org-ql.info

@@ -530,24 +530,27 @@ File: README.info,  Node: Date/time predicates,  Prev: Ancestor/descendant predi
 4.2.4 Date/time predicates
 --------------------------
 
-All of these predicates take optional keyword arguments ‘:from’, ‘:to:’,
-and ‘:on’:
+These predicates take optional keyword arguments:
 
-   • If ‘:from’, return non-nil if entry has a timestamp on or after
+   • ‘:from’: Match entries whose timestamp is on or after timestamp
      ‘:from’.
-   • If ‘:to’, return non-nil if entry has a timestamp on or before
+   • ‘:to’: Match entries whose timestamp is on or before timestamp
      ‘:to’.
-   • If ‘:on’, return non-nil if entry has a timestamp on date ‘:on’.
+   • ‘:on’: Match entries whose timestamp is on date ‘:on’.
+   • ‘:with-time’: If unspecified, match timestamps with or without
+     times (i.e.  HH:MM). If nil, match timestamps without times.  If t,
+     match timestamps with times.
 
-   Argument values should be either a number of days (positive to look
-forward, or negative to look backward), a ‘ts’ struct, or a string
-parseable by ‘parse-time-string’ (the string may omit the time value).
+   Timestamp/date arguments should be either a number of days (positive
+to look forward, or negative to look backward), a string parseable by
+‘parse-time-string’ (the string may omit the time value), or a ‘ts’
+struct.
 
    • *Predicates*
      ‘ts’
           Return non-nil if current entry has a timestamp in given
-          period.  If no arguments are specified, return non-nil if
-          entry has any timestamp.
+          period.  Without arguments, return non-nil if entry has a
+          timestamp.
      ‘ts-active, ts-a’
           Like ts, but only matches active timestamps.
      ‘ts-inactive, ts-i’
@@ -560,30 +563,28 @@ number of days.  The number can be negative to invert the direction.
    • *Backward-looking*
      ‘clocked’
           Return non-nil if current entry was clocked in given period.
-          If no arguments are specified, return non-nil if entry was
-          clocked at any time.  Note: Clock entries are expected to be
-          clocked out.  Currently clocked entries (i.e.  with unclosed
-          timestamp ranges) are ignored.
+          Without arguments, return non-nil if entry was ever clocked.
+          Note: Clock entries are expected to be clocked out.  Currently
+          clocked entries (i.e.  with unclosed timestamp ranges) are
+          ignored.
      ‘closed’
           Return non-nil if current entry was closed in given period.
-          If no arguments are specified, return non-nil if entry was
-          closed at any time.
+          Without arguments, return non-nil if entry is closed.
 
    • *Forward-looking*
      ‘deadline’
           Return non-nil if current entry has deadline in given period.
           If argument is auto, return non-nil if entry has deadline
-          within org-deadline-warning-days.  If no arguments are
-          specified, return non-nil if entry has any deadline.
+          within org-deadline-warning-days.  Without arguments, return
+          non-nil if entry has any deadline.
      ‘planning’
-          Return non-nil if current entry has planning timestamp in
-          given period (i.e.  its deadline, scheduled, or closed
-          timestamp).  If no arguments are specified, return non-nil if
-          entry is scheduled at any time.
+          Return non-nil if current entry has planning timestamp (i.e.
+          its deadline, scheduled, or closed timestamp) in given period.
+          Without arguments, return non-nil if entry has any planning
+          timestamp.
      ‘scheduled’
           Return non-nil if current entry is scheduled in given period.
-          If no arguments are specified, return non-nil if entry is
-          scheduled at any time.
+          Without arguments, return non-nil if entry is scheduled.
 
 
 File: README.info,  Node: Functions / Macros,  Next: Dynamic block,  Prev: Queries,  Up: Usage
@@ -981,6 +982,9 @@ File: README.info,  Node: 06-pre,  Next: 052,  Up: Changelog
    • Predicate ‘effort’.
    • Predicate ‘heading-regexp’, which matches regular expressions
      against heading text (alias: ‘h*’).
+   • Timestamp-related predicates now accept an optional ‘:with-time’
+     argument, which allows matching timestamps with or without times
+     (i.e.  HH:MM).
 
    *Changed*
    • Helm support (including the command helm-org-ql) has been moved to
@@ -1534,40 +1538,40 @@ Node: Non-sexp query syntax9485
 Node: General predicates11209
 Node: Ancestor/descendant predicates17430
 Node: Date/time predicates18558
-Node: Functions / Macros21213
-Node: Agenda-like views21511
-Node: Listing / acting-on results22916
-Node: Custom predicates28538
-Node: Dynamic block32029
-Node: Links34727
-Node: Tips35414
-Node: Changelog35732
-Node: 06-pre36458
-Node: 05237865
-Node: 05138169
-Node: 0538586
-Node: 04940060
-Node: 04840334
-Node: 04740681
-Node: 04641076
-Node: 04541476
-Node: 04441835
-Node: 04342194
-Node: 04242391
-Node: 04142552
-Node: 0442793
-Node: 03246726
-Node: 03147105
-Node: 0347302
-Node: 02350277
-Node: 02250505
-Node: 02150773
-Node: 0250972
-Node: 0155007
-Node: Notes55108
-Node: Comparison with Org Agenda searches55270
-Node: org-sidebar56142
-Node: License56421
+Node: Functions / Macros21220
+Node: Agenda-like views21518
+Node: Listing / acting-on results22923
+Node: Custom predicates28545
+Node: Dynamic block32036
+Node: Links34734
+Node: Tips35421
+Node: Changelog35739
+Node: 06-pre36465
+Node: 05238038
+Node: 05138342
+Node: 0538759
+Node: 04940233
+Node: 04840507
+Node: 04740854
+Node: 04641249
+Node: 04541649
+Node: 04442008
+Node: 04342367
+Node: 04242564
+Node: 04142725
+Node: 0442966
+Node: 03246899
+Node: 03147278
+Node: 0347475
+Node: 02350450
+Node: 02250678
+Node: 02150946
+Node: 0251145
+Node: 0155180
+Node: Notes55281
+Node: Comparison with Org Agenda searches55443
+Node: org-sidebar56315
+Node: License56594
 
 End Tag Table