* bug#54782: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API
@ 2022-04-08 3:52 Kaushal Modi
2022-04-08 13:17 ` Lars Ingebrigtsen
0 siblings, 1 reply; 8+ messages in thread
From: Kaushal Modi @ 2022-04-08 3:52 UTC (permalink / raw)
To: 54782, larsi
[-- Attachment #1: Type: text/plain, Size: 388 bytes --]
Hello,
I have reading through the shortdoc documentation and in the process
ended up with these edits. Can someone please review this?
I have my copyright assigned and I have access to the Emacs git repo.
But I cannot access it via git/SSH protocol (due to technical reasons
at work). So once the patch is ready, I'll need someone's help to
commit it as well.
Thanks!
--
Kaushal Modi
[-- Attachment #2: 0001-Update-docstrings-for-shortdoc.el-FUNC-lisp-form-API.patch --]
[-- Type: application/octet-stream, Size: 3983 bytes --]
From 52cfc59b28571ba5c06084ac7c1f38f4a56dcc6f Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
Date: Thu, 7 Apr 2022 15:15:58 -0400
Subject: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API
* lisp/emacs-lisp/shortdoc.el (define-short-documentation-group)
(shortdoc-add-function): Updated docstrings.
---
lisp/emacs-lisp/shortdoc.el | 71 +++++++++++++++++++++++++++++--------
1 file changed, 57 insertions(+), 14 deletions(-)
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 99035c9e89..6fd4d41564 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -47,30 +47,70 @@ define-short-documentation-group
"Add GROUP to the list of defined documentation groups.
FUNCTIONS is a list of elements on the form:
- (fun
+ (FUNC
:no-manual BOOL
:args ARGS
- :eval EXAMPLE-FORM
+ :eval EVAL
:no-eval EXAMPLE-FORM
- :no-eval* EXAMPLE-FORM
:no-value EXAMPLE-FORM
+ :no-eval* EXAMPLE-FORM
:result RESULT-FORM
- :result-string RESULT-FORM
+ :result-string RESULT-STRING
:eg-result RESULT-FORM
- :eg-result-string RESULT-FORM)
+ :eg-result-string RESULT-STRING)
-BOOL should be non-nil if the function isn't documented in the
+FUNC is the function being documented.
+
+NO-MANUAL should be non-nil if FUNC isn't documented in the
manual.
-ARGS is optional; the function's signature is displayed if ARGS
-is not present.
+ARGS is optional list of function FUNC's arguments. FUNC's
+signature is displayed automatically if ARGS is not present.
+Specifying ARGS might be useful where you don't want to document
+some of the uncommon arguments a function might have.
+
+While the `:no-manual' and `:args' property can be used for
+any (FUNC ..) form, all of the other properties shown above
+cannot be used simultaneously in such a form.
+
+Here are some common forms with examples of properties that go
+together:
+
+1. Document a form or string, and its evaluated return value.
+ (FUNC
+ :eval EVAL)
If EVAL isn't a string, it will be printed with `prin1', and then
-evaluated to give a result, which is also printed. If it's a
-string, it'll be inserted as is, then the string will be `read',
-and then evaluated.
+evaluated to give a result, which is also printed.
+
+If EVAL is a string, it will be inserted as is, and then that
+string will be `read' and evaluated.
+
+2. Document a form or string, but manually document its evalation
+ result. The provided form will not be evaluated.
-There can be any number of :example/:result elements."
+ (FUNC
+ :no-eval EXAMPLE-FORM
+ :result RESULT-FORM ;Use `:result-string' if value is in string form
+ )
+
+Using `:no-value' is the same as using `:no-eval'.
+
+Use `:no-eval*' instead of `:no-eval' where the successful
+execution of the documented form depends on some conditions.
+
+3. Document a form or string EXAMPLE-FORM. Also manually
+ document an example result. This result could be unrelated to
+ the documented form.
+
+ (FUNC
+ :no-eval EXAMPLE-FORM
+ :eg-result RESULT-FORM ;Use `:eg-result-string' if value is in string form
+ )
+
+A FUNC form can have any number of `:no-eval' (or `:no-value'),
+`:no-eval*', `:result', `:result-string', `:eg-result' and
+`:eg-result-string' properties."
`(progn
(setq shortdoc--groups (delq (assq ',group shortdoc--groups)
shortdoc--groups))
@@ -1351,11 +1391,14 @@ shortdoc-add-function
If GROUP doesn't exist, it will be created.
If SECTION doesn't exist, it will be added.
+ELEM is a Lisp form. See `define-short-documentation-group' for
+details.
+
Example:
(shortdoc-add-function
- 'file \"Predicates\"
- '(file-locked-p :no-eval (file-locked-p \"/tmp\")))"
+ \\='file \"Predicates\"
+ \\='(file-locked-p :no-eval (file-locked-p \"/tmp\")))"
(let ((glist (assq group shortdoc--groups)))
(unless glist
(setq glist (list group))
--
2.34.0
^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#54782: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API
2022-04-08 3:52 bug#54782: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API Kaushal Modi
@ 2022-04-08 13:17 ` Lars Ingebrigtsen
2022-04-08 13:18 ` Kaushal Modi
0 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-04-08 13:17 UTC (permalink / raw)
To: Kaushal Modi; +Cc: 54782
Kaushal Modi <kaushal.modi@gmail.com> writes:
> I have reading through the shortdoc documentation and in the process
> ended up with these edits. Can someone please review this?
The patch doesn't apply to the current master. Can you respin it?
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#54782: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API
2022-04-08 13:17 ` Lars Ingebrigtsen
@ 2022-04-08 13:18 ` Kaushal Modi
2022-04-09 9:45 ` Lars Ingebrigtsen
0 siblings, 1 reply; 8+ messages in thread
From: Kaushal Modi @ 2022-04-08 13:18 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 54782
On Fri, Apr 8, 2022 at 9:17 AM Lars Ingebrigtsen <larsi@gnus.org> wrote:
> The patch doesn't apply to the current master. Can you respin it?
I have based it off emacs-28 as it's just a doc change.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#54782: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API
2022-04-08 13:18 ` Kaushal Modi
@ 2022-04-09 9:45 ` Lars Ingebrigtsen
2022-04-09 17:23 ` Kaushal Modi
0 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-04-09 9:45 UTC (permalink / raw)
To: Kaushal Modi; +Cc: 54782
Kaushal Modi <kaushal.modi@gmail.com> writes:
> I have based it off emacs-28 as it's just a doc change.
We merge forward to emacs-29, and since this can't be merged as is, I'd
rather it go to emacs-29 directly.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#54782: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API
2022-04-09 9:45 ` Lars Ingebrigtsen
@ 2022-04-09 17:23 ` Kaushal Modi
2022-04-10 11:52 ` Lars Ingebrigtsen
0 siblings, 1 reply; 8+ messages in thread
From: Kaushal Modi @ 2022-04-09 17:23 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 54782
[-- Attachment #1: Type: text/plain, Size: 249 bytes --]
On Sat, Apr 9, 2022 at 5:45 AM Lars Ingebrigtsen <larsi@gnus.org> wrote:
> We merge forward to emacs-29, and since this can't be merged as is, I'd
> rather it go to emacs-29 directly.
OK, I have attached that patch now rebased to master.
Thanks!
[-- Attachment #2: 0001-Update-docstrings-for-shortdoc.el-FUNC-lisp-form-API.patch --]
[-- Type: application/octet-stream, Size: 3989 bytes --]
From dfeee23aae58a2cca72be1a0cad4c6e3f3e8f206 Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
Date: Thu, 7 Apr 2022 15:15:58 -0400
Subject: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API
* lisp/emacs-lisp/shortdoc.el (define-short-documentation-group):
Updated docstrings.
(shortdoc-add-function): Escape single quotes so that they don't
convert to curved quotes in *Help* buffers.
---
lisp/emacs-lisp/shortdoc.el | 70 +++++++++++++++++++++++++++++--------
1 file changed, 55 insertions(+), 15 deletions(-)
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 658edd6752..ebf3c6b1fe 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -47,30 +47,67 @@ define-short-documentation-group
"Add GROUP to the list of defined documentation groups.
FUNCTIONS is a list of elements on the form:
- (fun
+ (FUNC
:no-manual BOOL
:args ARGS
- :eval EXAMPLE-FORM
+ :eval EVAL
:no-eval EXAMPLE-FORM
- :no-eval* EXAMPLE-FORM
:no-value EXAMPLE-FORM
+ :no-eval* EXAMPLE-FORM
:result RESULT-FORM
- :result-string RESULT-FORM
+ :result-string RESULT-STRING
:eg-result RESULT-FORM
- :eg-result-string RESULT-FORM)
+ :eg-result-string RESULT-STRING)
-BOOL should be non-nil if the function isn't documented in the
+FUNC is the function being documented.
+
+NO-MANUAL should be non-nil if FUNC isn't documented in the
manual.
-ARGS is optional; the function's signature is displayed if ARGS
-is not present.
+ARGS is optional list of function FUNC's arguments. FUNC's
+signature is displayed automatically if ARGS is not present.
+Specifying ARGS might be useful where you don't want to document
+some of the uncommon arguments a function might have.
+
+While the `:no-manual' and `:args' property can be used for
+any (FUNC ..) form, all of the other properties shown above
+cannot be used simultaneously in such a form.
-If EVAL isn't a string, it will be printed with `prin1', and then
-evaluated to give a result, which is also printed. If it's a
-string, it'll be inserted as is, then the string will be `read',
-and then evaluated.
+Here are some common forms with examples of properties that go
+together:
-There can be any number of :example/:result elements."
+1. Document a form or string, and its evaluated return value.
+ (FUNC
+ :eval EVAL)
+
+If EVAL is a string, it will be inserted as is, and then that
+string will be `read' and evaluated.
+
+2. Document a form or string, but manually document its evalation
+ result. The provided form will not be evaluated.
+
+ (FUNC
+ :no-eval EXAMPLE-FORM
+ :result RESULT-FORM ;Use `:result-string' if value is in string form
+ )
+
+Using `:no-value' is the same as using `:no-eval'.
+
+Use `:no-eval*' instead of `:no-eval' where the successful
+execution of the documented form depends on some conditions.
+
+3. Document a form or string EXAMPLE-FORM. Also manually
+ document an example result. This result could be unrelated to
+ the documented form.
+
+ (FUNC
+ :no-eval EXAMPLE-FORM
+ :eg-result RESULT-FORM ;Use `:eg-result-string' if value is in string form
+ )
+
+A FUNC form can have any number of `:no-eval' (or `:no-value'),
+`:no-eval*', `:result', `:result-string', `:eg-result' and
+`:eg-result-string' properties."
(declare (indent defun))
`(progn
(setq shortdoc--groups (delq (assq ',group shortdoc--groups)
@@ -1408,11 +1445,14 @@ shortdoc-add-function
If GROUP doesn't exist, it will be created.
If SECTION doesn't exist, it will be added.
+ELEM is a Lisp form. See `define-short-documentation-group' for
+details.
+
Example:
(shortdoc-add-function
- 'file \"Predicates\"
- '(file-locked-p :no-eval (file-locked-p \"/tmp\")))"
+ \\='file \"Predicates\"
+ \\='(file-locked-p :no-eval (file-locked-p \"/tmp\")))"
(let ((glist (assq group shortdoc--groups)))
(unless glist
(setq glist (list group))
--
2.34.0
^ permalink raw reply related [flat|nested] 8+ messages in thread
end of thread, other threads:[~2022-04-10 13:47 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-04-08 3:52 bug#54782: [PATCH] Update docstrings for shortdoc.el FUNC lisp form API Kaushal Modi
2022-04-08 13:17 ` Lars Ingebrigtsen
2022-04-08 13:18 ` Kaushal Modi
2022-04-09 9:45 ` Lars Ingebrigtsen
2022-04-09 17:23 ` Kaushal Modi
2022-04-10 11:52 ` Lars Ingebrigtsen
2022-04-10 13:44 ` Kaushal Modi
2022-04-10 13:47 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).