bug#7509: 24.0.50; doc for `comment-style' and `comment-styles'

[Stefan Monnier]

Can you try the patch below and tell us if it addresses your problem
(I'm not that happy with the doc for some of those styles, so if you
have suggestions for improvements, I'm all ears).


        Stefan
        
        
=== modified file 'lisp/newcomment.el'
--- lisp/newcomment.el  2010-10-22 13:45:31 +0000
+++ lisp/newcomment.el  2010-11-29 18:26:11 +0000
@@ -187,16 +187,18 @@
 it is 1 so that regions are commented with two or three semi-colons.")
 
 (defconst comment-styles
-  '((plain     . (nil nil nil nil))
-    (indent    . (nil nil nil t))
+  '((plain    nil nil nil nil "Comment in column 0"))
+    (indent   nil nil nil t "Indented as code"))
     (indent-or-triple
-                . (nil nil nil multi-char))
-    (aligned   . (nil t nil t))
-    (multi-line        . (t nil nil t))
-    (extra-line        . (t nil t t))
-    (box       . (nil t t t))
-    (box-multi . (t t t t)))
-  "Comment region styles of the form (STYLE . (MULTI ALIGN EXTRA INDENT)).
+                nil nil nil multi-char "Indent only multi-char starters"))
+    (aligned   nil t nil t "Indented and with closers aligned"))
+    (multi-line        t nil nil t "Use multi-line comments"))
+    (extra-line        t nil t   t "Multi-line with starter&ender on their own 
line"))
+    (box       nil t t   t "Wrap comments in boxes"))
+    (box-multi t   t t   t "Boxes using multi-line comments")))
+  "Comment region style definitions.
+Each style is defined with a form (STYLE . (MULTI ALIGN EXTRA INDENT DOC)).
+DOC should succinctly describe the style.
 STYLE should be a mnemonic symbol.
 MULTI specifies that comments are allowed to span multiple lines.
 ALIGN specifies that the `comment-end' markers should be aligned.
@@ -210,7 +212,8 @@
 (defcustom comment-style 'indent
   "Style to be used for `comment-region'.
 See `comment-styles' for a list of available styles."
-  :type `(choice ,@(mapcar (lambda (s) `(const ,(car s))) comment-styles))
+  :type `(choice ,@(mapcar (lambda (s) `(const :tag ,(nth 5 s) ,(car s)))
+                           comment-styles))
   :version "23.1"
   :group 'comment)