bug#35994: Remove leading '*' from defcustom docstring todo considered done

bug#35994: Remove leading '*' from defcustom docstring todo considered done

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 633 bytes --]

I looked into the following item in etc/TODO:

> ** Remove any leading '*'s from defcustom doc-strings.
> [done?] [A lot of them are in CC Mode.]

I couldn't find one example.  Therefore, I propose that this should be
considered done.  I've attached a patch that removes the TODO.

I carried out the following steps, in case anyone wants to verify:

1. find . -type f -name "*.el" -exec grep -Hn -A20 "(defcustom" {} \; > output
2. grep '\*' output > output.filtered
3. Checked output.filtered manually (<< least fun step)

I'm sure there's a better way to do this, but I couldn't be bothered to think of
one.

Thanks,
Stefan Kangas

[-- Attachment #2: 0001-etc-TODO-Remove-done-TODO-to-remove-leading-from-def.patch --]
[-- Type: application/octet-stream, Size: 840 bytes --]

From b00e25b6a7caf8de7e874613377223125c85cb93 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Wed, 29 May 2019 18:49:07 +0200
Subject: [PATCH] * etc/TODO: Remove done TODO to remove leading "*" from
 defcustoms.

---
 etc/TODO | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/etc/TODO b/etc/TODO
index fe2e583a38..0f93279fa6 100644
--- a/etc/TODO
+++ b/etc/TODO
@@ -125,9 +125,6 @@ to use it.
 ** Convert all defvars with leading '*' in the doc-strings into defcustoms
 of appropriate :type and :group.
 
-** Remove any leading '*'s from defcustom doc-strings.
-[done?] [A lot of them are in CC Mode.]
-
 ** Remove unnecessary autoload cookies from defcustoms.
 This needs a bit of care, since often people have become used to
 expecting such variables to always be defined, eg when they modify
-- 
2.21.0

bug#35994: Remove leading '*' from defcustom docstring todo considered done

[Basil L. Contovounesios]

severity 35994 minor
quit

Stefan Kangas <stefan@marxist.se> writes:

> I looked into the following item in etc/TODO:
>
>> ** Remove any leading '*'s from defcustom doc-strings.
>> [done?] [A lot of them are in CC Mode.]
>
> I couldn't find one example.  Therefore, I propose that this should be
> considered done.  I've attached a patch that removes the TODO.
>
> I carried out the following steps, in case anyone wants to verify:
>
> 1. find . -type f -name "*.el" -exec grep -Hn -A20 "(defcustom" {} \; > output
> 2. grep '\*' output > output.filtered
> 3. Checked output.filtered manually (<< least fun step)

There is also at least one defface (ibuffer-locked-buffer), and the
defvars in lisp/obsolete/cc-compat.el (I just did a quick rgrep '^  "\*').

Thanks,

-- 
Basil

bug#35994: Remove leading '*' from defcustom docstring todo considered done

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 727 bytes --]

Basil L. Contovounesios <contovob@tcd.ie> writes:
> There is also at least one defface (ibuffer-locked-buffer), and the

Please find attached an updated patch fixing this - thanks.

> defvars in lisp/obsolete/cc-compat.el (I just did a quick rgrep '^  "\*').

This is related to the TODO:

 ** Convert all defvars with leading '*' in the doc-strings into defcustoms
  of appropriate :type and :group.

I have attached a second patch which fixes this TODO item.

I didn't bother converting the defvar cases in lisp/obsolete/cc-compat.el to
defcustom since I don't feel like it's a good idea to expose this obsolete code
to the user more than necessary.  We should let it rest in peace. What do you
think?

Thanks,
Stefan Kangas

[-- Attachment #2: 0002-Fix-TODO-to-convert-defvar-with-leading-to-defcustom.patch --]
[-- Type: application/octet-stream, Size: 5791 bytes --]

From cb31cfb286526fb31bc43ce77c67a580ffa4909f Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Thu, 30 May 2019 13:05:46 +0200
Subject: [PATCH 2/2] Fix TODO to convert defvar with leading '*' to defcustom

* etc/TODO: Remove done TODO to remove '*' from defvar.
* doc/misc/gnus.texi: Remove leading '*' from defvar example.
* lisp/kermit.el (kermit-esc-char): Convert to defcustom.
* lisp/desktop.el (desktop-header):
* lisp/obsolete/cc-compat.el (c-indent-level)
(c-brace-imaginary-offset, c-brace-offset, c-argdecl-indent)
(c-label-offset, c-continued-statement-offset)
(c-continued-brace-offset): Remove leading '*' from docstring.
* lisp/progmodes/dcl-mode.el: Remove leading '*' from docstring in
comment.
* test/manual/cedet/tests/test.el: Add comment asking if example of
defvar with leading '*' should be removed.
---
 doc/misc/gnus.texi              |  2 +-
 etc/TODO                        |  3 ---
 lisp/desktop.el                 |  2 +-
 lisp/kermit.el                  |  8 +++++++-
 lisp/obsolete/cc-compat.el      | 14 +++++++-------
 lisp/progmodes/dcl-mode.el      |  2 +-
 test/manual/cedet/tests/test.el |  1 +
 7 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 17b1521f48..11ee62d546 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -30451,7 +30451,7 @@ Writing New Back Ends
   nnml-current-directory nnmh-current-directory)
 
 (defvoo nndir-nov-is-evil nil
-  "*Non-nil means that nndir will never retrieve NOV headers."
+  "Non-nil means that nndir will never retrieve NOV headers."
   nnml-nov-is-evil)
 
 (defvoo nndir-current-group ""
diff --git a/etc/TODO b/etc/TODO
index 0f93279fa6..f8c2d285ee 100644
--- a/etc/TODO
+++ b/etc/TODO
@@ -122,9 +122,6 @@ It can use the same icons as gud.
 ** Check what minor modes don't use define-minor-mode and convert them
 to use it.
 
-** Convert all defvars with leading '*' in the doc-strings into defcustoms
-of appropriate :type and :group.
-
 ** Remove unnecessary autoload cookies from defcustoms.
 This needs a bit of care, since often people have become used to
 expecting such variables to always be defined, eg when they modify
diff --git a/lisp/desktop.el b/lisp/desktop.el
index 33d7643d1b..59610a128a 100644
--- a/lisp/desktop.el
+++ b/lisp/desktop.el
@@ -616,7 +616,7 @@ desktop-header
 ";; --------------------------------------------------------------------------
 ;; Desktop File for Emacs
 ;; --------------------------------------------------------------------------
-" "*Header to place in Desktop file.")
+" "Header to place in Desktop file.")
 
 (defvar desktop-delay-hook nil
   "Hooks run after all buffers are loaded; intended for internal use.")
diff --git a/lisp/kermit.el b/lisp/kermit.el
index f6ed1fbda1..ec5d91749c 100644
--- a/lisp/kermit.el
+++ b/lisp/kermit.el
@@ -77,7 +77,13 @@
 
 (require 'shell)
 
-(defvar kermit-esc-char "\C-\\" "*Kermit's escape char.")
+(defgroup kermit nil
+  "Kermit support."
+  :group 'comm)
+
+(defcustom kermit-esc-char "\C-\\"
+  "Kermit's escape char."
+  :type 'string)
 
 (defun kermit-esc ()
   "For sending escape sequences to a kermit running in shell mode."
diff --git a/lisp/obsolete/cc-compat.el b/lisp/obsolete/cc-compat.el
index bbacd12113..8e9d9e7262 100644
--- a/lisp/obsolete/cc-compat.el
+++ b/lisp/obsolete/cc-compat.el
@@ -59,21 +59,21 @@
 \f
 ;; In case c-mode.el isn't loaded
 (defvar c-indent-level 2
-  "*Indentation of C statements with respect to containing block.")
+  "Indentation of C statements with respect to containing block.")
 ;;;###autoload(put 'c-indent-level 'safe-local-variable 'integerp)
 
 (defvar c-brace-imaginary-offset 0
-  "*Imagined indentation of a C open brace that actually follows a statement.")
+  "Imagined indentation of a C open brace that actually follows a statement.")
 (defvar c-brace-offset 0
-  "*Extra indentation for braces, compared with other text in same context.")
+  "Extra indentation for braces, compared with other text in same context.")
 (defvar c-argdecl-indent 5
-  "*Indentation level of declarations of C function arguments.")
+  "Indentation level of declarations of C function arguments.")
 (defvar c-label-offset -2
-  "*Offset of C label lines and case statements relative to usual indentation.")
+  "Offset of C label lines and case statements relative to usual indentation.")
 (defvar c-continued-statement-offset 2
-  "*Extra indent for lines not starting new statements.")
+  "Extra indent for lines not starting new statements.")
 (defvar c-continued-brace-offset 0
-  "*Extra indent for substatements that start with open-braces.
+  "Extra indent for substatements that start with open-braces.
 This is in addition to c-continued-statement-offset.")
 
 
diff --git a/lisp/progmodes/dcl-mode.el b/lisp/progmodes/dcl-mode.el
index d5803c77bb..864074fe19 100644
--- a/lisp/progmodes/dcl-mode.el
+++ b/lisp/progmodes/dcl-mode.el
@@ -459,7 +459,7 @@ dcl-option-history
 ;    ("GOSUB" (, (concat dcl-cmd-r
 ;			"GOSUB[ \t]+\\([A-Za-z0-9_$]+\\)")) 5)
 ;    ("CALL" (, (concat dcl-cmd-r "CALL[ \t]+\\([A-Za-z0-9_$]+\\)")) 5)))
-;  "*Default imenu generic expression for DCL.
+;  "Default imenu generic expression for DCL.
 
 ;The default includes SUBROUTINE labels in the main listing and
 ;sub-listings for other labels, CALL, GOTO and GOSUB statements.
diff --git a/test/manual/cedet/tests/test.el b/test/manual/cedet/tests/test.el
index 242186c360..8f551da5fe 100644
--- a/test/manual/cedet/tests/test.el
+++ b/test/manual/cedet/tests/test.el
@@ -83,6 +83,7 @@ existing-function-to-advise
 (defvar a-defvar (cons 1 2)
   "Variable a")
 
+;; FIXME: This practice is not recommended in recent Emacs.  Remove?
 (defvar a-defvar-star (cons 1 2)
   "*User visible var a")
 
-- 
2.21.0


[-- Attachment #3: 0001-Fix-TODO-to-remove-leading-from-defcustom.patch --]
[-- Type: application/octet-stream, Size: 1490 bytes --]

From 546ebababfe8ac271ae9fef497179660936c044c Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Wed, 29 May 2019 18:49:07 +0200
Subject: [PATCH 1/2] Fix TODO to remove leading '*' from defcustom

* etc/TODO: Remove done TODO to remove leading '*' from defcustom
doc-strings.
* lisp/ibuffer.el (ibuffer-inline-columns): Remove leading '*' from
doc-string.
---
 etc/TODO        | 3 ---
 lisp/ibuffer.el | 2 +-
 2 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/etc/TODO b/etc/TODO
index fe2e583a38..0f93279fa6 100644
--- a/etc/TODO
+++ b/etc/TODO
@@ -125,9 +125,6 @@ to use it.
 ** Convert all defvars with leading '*' in the doc-strings into defcustoms
 of appropriate :type and :group.
 
-** Remove any leading '*'s from defcustom doc-strings.
-[done?] [A lot of them are in CC Mode.]
-
 ** Remove unnecessary autoload cookies from defcustoms.
 This needs a bit of care, since often people have become used to
 expecting such variables to always be defined, eg when they modify
diff --git a/lisp/ibuffer.el b/lisp/ibuffer.el
index 628e884094..929336c479 100644
--- a/lisp/ibuffer.el
+++ b/lisp/ibuffer.el
@@ -1809,7 +1809,7 @@ ibuffer-inline-columns
 (defface ibuffer-locked-buffer
   '((((background dark)) (:foreground "RosyBrown"))
     (t (:foreground "brown4")))
-  "*Face used for locked buffers in Ibuffer."
+  "Face used for locked buffers in Ibuffer."
   :version "26.1"
   :group 'ibuffer
   :group 'font-lock-highlighting-faces)
-- 
2.21.0

bug#35994: Remove leading '*' from defcustom docstring todo considered done

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 3 Jun 2019 02:43:59 +0200
> Cc: 35994@debbugs.gnu.org
> 
> Basil L. Contovounesios <contovob@tcd.ie> writes:
> > There is also at least one defface (ibuffer-locked-buffer), and the
> 
> Please find attached an updated patch fixing this - thanks.
> 
> > defvars in lisp/obsolete/cc-compat.el (I just did a quick rgrep '^  "\*').
> 
> This is related to the TODO:
> 
>  ** Convert all defvars with leading '*' in the doc-strings into defcustoms
>   of appropriate :type and :group.
> 
> I have attached a second patch which fixes this TODO item.

Thanks, I pushed this to the master branch.

Please in the future, if you send several patches that change the same
files, be sure to arrange them in the order you made the changes,
because otherwise they might fail to apply.  In this case you sent the
patches in the reverse order; I was lucky to be able to figure out
that they need to be applied in reverse.

(In general, if you change the same files for reasons that are closely
related, like in this case, sending a single patch makes the job of
installing easier.)