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

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

diff --git a/kubed.el b/kubed.el
index ee0c918710e6117f5b5b5abd2492a22cd76b4f80..ecb93d4a193ca44e1a1ebe102d61536da2efa0dd 100644 (file)
--- 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