From: Eshel Yaron <me@eshelyaron.com>
Date: Sat, 4 Jan 2025 16:13:46 +0000 (+0100)
Subject: * kubed.el (kubed-define-resource): Improve docstring.
X-Git-Tag: v0.4.3~4
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0f049c0b466e21eff69430d7a27239ff6bf55f6a;p=kubed.git

* kubed.el (kubed-define-resource): Improve docstring.

Addresses https://github.com/eshelyaron/kubed/issues/8
---

diff --git a/kubed.el b/kubed.el
index ee0c918..ecb93d4 100644
--- a/kubed.el
+++ b/kubed.el
@@ -1182,14 +1182,21 @@ value of PROP when applied to the JSON representation of a RESOURCE.
 WIDTH, SORT, FORMAT and ATTRS are optional and can be omitted.  WIDTH is
 used as the default width of the column corresponding to PROP in
 RESOURCEs list buffers; SORT is sort predicate, a function that takes
-two values of PROP as strings and return non-nil if the first should
+two values of PROP as strings and returns non-nil if the first should
 sort before the second; FORMAT is a function that takes a value of PROP
-and formats it; and ATTRS is a plist of additional attributes of the
-PROP column, see `tabulated-list-format' for available attributes.  For
-example, (phase \".status.phase\" 10) says that RESOURCE has a `phase'
-property at JSONPath \".status.phase\" whose values are typically 10
-columns wide.  The first property in PROPERTIES, is used to annotate
-completion candidates when prompting for a RESOURCE.
+and formats it.  If you provide a FORMAT function and a SORT function,
+then the SORT function gets the formatted values (the output of the
+FORMAT function), not the original values.  If you want to sort based on
+the unformatted original values, you can store them as text properties
+in your FORMAT function and access them in your SORT function.
+
+ATTRS is a plist of additional attributes of the PROP column, see
+`tabulated-list-format' for available attributes.
+
+For example, if PROPERTIES is (phase \".status.phase\" 10) that means
+that RESOURCE has a `phase' property at JSONPath \".status.phase\" whose
+values are typically 10 columns wide.  The first property in PROPERTIES
+is used to annotate completion candidates when prompting for a RESOURCE.
 
 COMMANDS is a list of elements (COMMAND KEYS DOC-PREFIX . BODY) that
 define commands for RESOURCE list buffers.  COMMAND is a symbol