From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id EMn7JX9pUmG0KAEAgWs5BA (envelope-from ) for ; Tue, 28 Sep 2021 03:01:51 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id OA+mIX9pUmHzBgAA1q6Kng (envelope-from ) for ; Tue, 28 Sep 2021 01:01:51 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id AAD2523D78 for ; Tue, 28 Sep 2021 03:01:50 +0200 (CEST) Received: from localhost ([::1]:51298 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mV1VF-00044u-Mr for larch@yhetil.org; Mon, 27 Sep 2021 21:01:49 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:49468) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mV1Uc-00044P-H8 for emacs-orgmode@gnu.org; Mon, 27 Sep 2021 21:01:10 -0400 Received: from mail-qt1-x835.google.com ([2607:f8b0:4864:20::835]:37686) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mV1UZ-0008J8-Nr for emacs-orgmode@gnu.org; Mon, 27 Sep 2021 21:01:10 -0400 Received: by mail-qt1-x835.google.com with SMTP id e16so15895091qts.4 for ; Mon, 27 Sep 2021 18:01:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=user-agent:from:to:subject:date:message-id:mime-version; bh=IvYVVpirQ8uSXBLCyJpofPLeKyG/YwXmKfeyXoSeC68=; b=L5DefZzjVZ4Qp/0Km65gvcB8kWRwdRl9I+8KOllllpbzre7SF3dQuaJEzagEdaFS2v na7Vb60kDMB9hIozkYzusiwlwhYUZZ7cQspeNYwqkSDYQayz5ObjtdpgHpQkoaK1yJTn 7+B39KpTWW4S2mo/BomUq35xuqgyb6JeHjKUmrakSpFOv+pVSCxGbfKj/BT1vxB6m4Ij oAgBuVYaDTv4CyYaacnwHj8pdybZFuMzaKXLO2A3BSYw461OU5/95+v2MMRojY0+YRi2 FA4vKoRQZe6Pk3uYEBg8v2W5KORWSalzAPhiC00zL7CfkhFR216uSAkZojUWGNdE80E3 OxSw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:user-agent:from:to:subject:date:message-id :mime-version; bh=IvYVVpirQ8uSXBLCyJpofPLeKyG/YwXmKfeyXoSeC68=; b=S4KWgbaZ03+6IsHeX2hW0Q3G3IikIfrKr61a1GHzKjoCfROzRDKIU9yxnRyahMF24q vy37zga2+5PRyaBSGZL6mJGWGnZN2ffs9QGWJCJGCXdk4dT0aFysoE0lZvr+IaRQplIM YxapimQaoY1PnigJsHCR+PbfApoQC3AtOme6JZp8ohxHWSgxZeyqYJk2OinLWaSV2Jkg 0XOkaoyIYPHmSCLHaXDA+az/lvyihV0/o8rkt3t9lmaDlMmouiPRt1l8aPSUbWq0U6QD ojcvwXs6nU0slM1RD5XylghqFjeJsFK8UGjDI2rlqI6CbWrUmOtc1+63QvCYGCboyOx2 z3Tg== X-Gm-Message-State: AOAM53152oO1yv6/2dhiBl5A+sqVnt5i17j3Baqs3nNDyqDZoiOLfANh L448f0LJvBTnB38J4OOZptSnTMErAKc= X-Google-Smtp-Source: ABdhPJyPh5buLirk9X8Ku3nI+3jMPMgoFNIiwPQjU+z5ZjS7fOKL9FrzoOGSqdVMwb6TfaznTkDttg== X-Received: by 2002:ac8:4149:: with SMTP id e9mr2932137qtm.106.1632790865975; Mon, 27 Sep 2021 18:01:05 -0700 (PDT) Received: from arch ([2601:82:c200:166d:afae:ebe6:a0e2:409e]) by smtp.gmail.com with ESMTPSA id e16sm12493890qtq.18.2021.09.27.18.01.04 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 27 Sep 2021 18:01:04 -0700 (PDT) User-agent: mu4e 1.7.0; emacs 28.0.50 From: No Wayman To: emacs-orgmode@gnu.org Subject: [PATCH] Fix org-capture checkdoc warnings [9.5 (9.5-g9364b2 @ /home/n/.emacs.d/straight/build/org/)] Date: Mon, 27 Sep 2021 20:51:31 -0400 Message-ID: <874ka5a4z4.fsf@gmail.com> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=2607:f8b0:4864:20::835; envelope-from=iarchivedmywholelife@gmail.com; helo=mail-qt1-x835.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1632790910; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=IvYVVpirQ8uSXBLCyJpofPLeKyG/YwXmKfeyXoSeC68=; b=oSoLi4ksgtYbLqRVLhLQ4pLdCVtbyu/WdhCVqCxYz3qZ0MbXx8TvsgFgW1QyQf+ILVhcPy kLPa2XiozRNLgeA0H831pLKki+Qm/N8akakhtFbGp0/dO2bfRXOMmnzrjV8gtNofHHe7z+ vr9wbm+5MojKtAPlmWY4d3psNL3/E8KftXYfpfrIWEpID71wqJ3W30o6nCVe2Gyvtoyf+L 1cSvWhJgvW8Vdg0U6c+VBYJOkUTeWVnkEZQHF6BTlZn72S3zSS36c99phSSQEn1kzXIVb9 +euws3Hs32iCzb7eCh3ytTPZUVWKT4wiz2MmhEwh9g+NsK9tHX4IUjiFY+ZWBQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1632790910; a=rsa-sha256; cv=none; b=pJ7dVNt7gVRTtc1WfYdy08kuNdA4q89OUwIkHjmNvrj0F6FCx5OAb2a3GSdUKBkruFgKk0 xDkaenXL7SYTuMZ5CJvi/dWYaTD0LO4ZjVwBXf712bEZkbr3oPzA8H/+egfTq9XPdKTPbV JuFnY6TVPvU1hfcNAl+RwQVsKFqiNDTWPd5izOX5WOLuW1x+9UhvdlL27NPxcC05dC9Rag FIIhoA0j4zk7YhUZFD5wATm3SSZxG00LYoRyK7VGYUQiyTibmtbr1aYiwuzdYALk9jsLXs mYsdzOUPOhcpW/jvTx6LSTZjc+R3q5lXPWzZhs04mmv3LcFj9UVe+2EmchAsFQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=L5DefZzj; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Spam-Score: -3.09 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=L5DefZzj; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Queue-Id: AAD2523D78 X-Spam-Score: -3.09 X-Migadu-Scanner: scn0.migadu.com X-TUID: D9k/j6e87ARz --=-=-= Content-Type: text/plain; format=flowed The attached patch addresses most of the checkdoc warnings for org-capture. There are two remaining warnings (both the same): > Disambiguate org-capture-mode by preceding w/ > function,command,variable,option or symbol. I did not address these because checkdoc has recently been fixed to stop asking for disambiguation of mode names: http://git.savannah.gnu.org/cgit/emacs.git/commit/?id=79a9b50621ec22640358bd6b94b65d14d747c644 --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-org-capture-Fix-checkdoc-warnings.patch >From 7f2e0e0a8735dbc2f4e79f17400471585e14d193 Mon Sep 17 00:00:00 2001 From: Nicholas Vollmer Date: Mon, 27 Sep 2021 20:35:12 -0400 Subject: [PATCH] org-capture: Fix checkdoc warnings * org-capture: Fix checkdoc warnings. --- lisp/org-capture.el | 71 +++++++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 32 deletions(-) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index cbdb30c03..15c62e14f 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -306,13 +306,15 @@ be replaced with content and expanded: current template. %(sexp) Evaluate elisp `(sexp)' and replace it with the results. Only placeholders pre-existing within the template, or - introduced with %[pathname] are expanded this way. Since this - happens after expanding non-interactive %-escapes, those can - be used to fill the expression. - %<...> The result of format-time-string on the ... format specification. - %t Time stamp, date only. The time stamp is the current time, - except when called from agendas with `\\[org-agenda-capture]' or - with `org-capture-use-agenda-date' set. + introduced with %[pathname] are expanded this way. + Since this happens after expanding non-interactive + %-escapes, those can be used to fill the expression. + %<...> The result of `format-time-string' on the ... format + specification. + %t Time stamp, date only. The time stamp is the current + time, except when called from agendas with + `\\[org-agenda-capture]' or with + `org-capture-use-agenda-date' set. %T Time stamp as above, with date and time. %u, %U Like the above, but inactive time stamps. %i Initial content, copied from the active region. If @@ -328,7 +330,7 @@ be replaced with content and expanded: %k Title of currently clocked task. %K Link to currently clocked task. %n User name (taken from the variable `user-full-name'). - %f File visited by current buffer when org-capture was called. + %f File visited by current buffer when `org-capture' was called. %F Full path of the file or directory visited by current buffer. %:keyword Specific information for certain link types, see below. %^g Prompt for tags, with completion on tags in target file. @@ -497,17 +499,17 @@ is copied to this variable, which is local in the indirect buffer.") "Local variable to store the value of the :clock-keep parameter. This is needed in case `org-capture-finalize' is called interactively.") -(defun org-capture-put (&rest stuff) - "Add properties to the capture property list `org-capture-plist'." - (while stuff +(defun org-capture-put (&rest elements) + "Add ELEMENTS to the capture property list `org-capture-plist'." + (while elements (setq org-capture-plist (plist-put org-capture-plist - (pop stuff) (pop stuff))))) -(defun org-capture-get (prop &optional local) - "Get properties from the capture property list `org-capture-plist'. + (pop elements) (pop elements))))) +(defun org-capture-get (property &optional local) + "Get PROPERTY from the capture property list `org-capture-plist'. When LOCAL is set, use the local variable `org-capture-current-plist', this is necessary after initialization of the capture process, to avoid conflicts with other active capture processes." - (plist-get (if local org-capture-current-plist org-capture-plist) prop)) + (plist-get (if local org-capture-current-plist org-capture-plist) property)) ;;; The minor mode @@ -1119,7 +1121,7 @@ FILE is a generalized file location, as handled by (defun org-capture-place-template (&optional inhibit-wconf-store) "Insert the template at the target location, and display the buffer. -When `inhibit-wconf-store', don't store the window configuration, as it +When INHIBIT-WCONF-STORE is non-nil, don't store the window configuration, as it may have been stored before." (unless inhibit-wconf-store (org-capture-put :return-to-wconf (current-window-configuration))) @@ -1414,21 +1416,21 @@ Of course, if exact position has been required, just put it there." (org-capture--position-cursor beg end))))) (defun org-capture-mark-kill-region (beg end) - "Mark the region that will have to be killed when aborting capture." + "Mark region between BEG and END to be killed on aborted capture." (let ((m1 (copy-marker beg)) (m2 (copy-marker end t))) (org-capture-put :begin-marker m1) (org-capture-put :end-marker m2))) -(defun org-capture-position-for-last-stored (where) - "Memorize the position that should later become the position of last capture." +(defun org-capture-position-for-last-stored (position) + "Put POSITION on `org-capture-plist' for future use as `last capture`." (cond - ((integerp where) + ((integerp position) (org-capture-put :position-for-last-stored - (move-marker (make-marker) where + (move-marker (make-marker) position (or (buffer-base-buffer (current-buffer)) (current-buffer))))) - ((eq where 'table-line) + ((eq position 'table-line) (org-capture-put :position-for-last-stored (list 'table-line (org-table-current-dline)))) @@ -1455,7 +1457,8 @@ Of course, if exact position has been required, just put it there." (move-marker org-capture-last-stored-marker (point)))))) (defun org-capture-narrow (beg end) - "Narrow, unless configuration says not to narrow." + "Possibly narrow to region between BEG and END. +If configuration contains non-nil :unnarrowed property, do not narrow." (unless (org-capture-get :unnarrowed) (narrow-to-region beg end))) @@ -1468,8 +1471,9 @@ of the template." (replace-match ""))) (defun org-capture-empty-lines-before (&optional n) - "Set the correct number of empty lines before the insertion point. -Point will be after the empty lines, so insertion can directly be done." + "Insert N empty lines before the insertion point. +Point will be after the empty lines, so insertion can directly be done. +If N is nil, :empty-lines-before or :empty-lines are considered." (setq n (or n (org-capture-get :empty-lines-before) (org-capture-get :empty-lines) 0)) (let ((pos (point))) @@ -1479,7 +1483,8 @@ Point will be after the empty lines, so insertion can directly be done." (defun org-capture-empty-lines-after (&optional n) "Set the correct number of empty lines after the inserted string. -Point will remain at the first line after the inserted text." +Point will remain at the first line after the inserted text. +If N is nil, :empty-lines-after or :empty-lines are considered." (setq n (or n (org-capture-get :empty-lines-after) (org-capture-get :empty-lines) 0)) (org-back-over-empty-lines) @@ -1491,7 +1496,7 @@ Point will remain at the first line after the inserted text." (defvar org-clock-marker) ; Defined in org.el (defun org-capture-set-plist (entry) - "Initialize the property list from the template definition." + "Initialize the property list for ENTRY from the template definition." (setq org-capture-plist (copy-sequence (nthcdr 5 entry))) (org-capture-put :key (car entry) :description (nth 1 entry) :target (nth 3 entry)) @@ -1508,7 +1513,7 @@ Point will remain at the first line after the inserted text." (defun org-capture-goto-target (&optional template-key) "Go to the target location of a capture template. -The user is queried for the template." +If TEMPLATE-KEY is nil, the user is queried for the template." (interactive) (let ((entry (org-capture-select-template template-key))) (unless entry (error "No capture template selected")) @@ -1518,7 +1523,7 @@ The user is queried for the template." (goto-char (org-capture-get :pos)))) (defun org-capture-get-indirect-buffer (&optional buffer prefix) - "Make an indirect buffer for a capture process. + "Make an indirect BUFFER for a capture process. Use PREFIX as a prefix for the name of the indirect buffer." (setq buffer (or buffer (current-buffer))) (let ((n 1) (base (buffer-name buffer)) bname) @@ -1560,8 +1565,10 @@ Lisp programs can force the template by setting KEYS to a string." "List various clipboards values.") (defun org-capture-fill-template (&optional template initial annotation) - "Fill a template and return the filled template as a string. -The template may still contain \"%?\" for cursor positioning." + "Fill a TEMPLATE and return the filled template as a string. +The template may still contain \"%?\" for cursor positioning. +INITIAL content and/or ANNOTATION may be specified, but will be overridden +by their respective `org-store-link-plist' properties if present." (let* ((template (or template (org-capture-get :template))) (buffer (org-capture-get :buffer)) (file (buffer-file-name (or (buffer-base-buffer buffer) buffer))) @@ -1848,7 +1855,7 @@ The template may still contain \"%?\" for cursor positioning." (defun org-capture-escaped-% () "Non-nil if % was escaped. -If yes, unescape it now. Assume match-data contains the +If yes, unescape it now. Assume `match-data' contains the placeholder to check." (save-excursion (goto-char (match-beginning 0)) -- 2.33.0 --=-=-=--