bug#3371: 23.0.94; doc of `comment-style'

bug#3371: 23.0.94; doc of `comment-style'

[Drew Adams]

Doc string:
 
"Style to be used for `comment-region'.
See `comment-styles' for a list of available styles."
 
1. Put the available styles here.
 
2. There is no such function or variable as `comment-styles'.
 
3. `comment-style' is mentioned in neither the Emacs manual nor the
Elisp manual.
 
IOW, there is really no doc explaining what this is, what it does, or
how it does it.
 
 
 
In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600)
 of 2009-05-24 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

bug#3371: 23.0.94; doc of `comment-style'

[martin rudalics]

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

 > "Style to be used for `comment-region'.
 > See `comment-styles' for a list of available styles."
 >
 > 1. Put the available styles here.
 >
 > 2. There is no such function or variable as `comment-styles'.

We probably could add two autoload cookies to newcomment.el (I don't
recall why I wanted the one for `comment-empty-lines' once).

martin

[-- Attachment #2: newcomment.el.diff --]
[-- Type: text/plain, Size: 1322 bytes --]

*** newcomment.el.~1.116.~	2009-01-05 09:59:16.000000000 +0100
--- newcomment.el	2009-05-25 08:36:37.000000000 +0200
***************
*** 185,190 ****
--- 185,191 ----
  This should generally stay 0, except for a few modes like Lisp where
  it is 1 so that regions are commented with two or three semi-colons.")
  
+ ;;;###autoload
  (defconst comment-styles
    '((plain	. (nil nil nil nil))
      (indent	. (nil nil nil t))
***************
*** 240,245 ****
--- 241,247 ----
    :type 'boolean
    :group 'comment)
  
+ ;;;###autoload
  (defcustom comment-empty-lines nil
    "If nil, `comment-region' does not comment out empty lines.
  If t, it always comments out empty lines.
***************
*** 1232,1238 ****
                               (buffer-substring (point)
                                                 (progn (move-to-left-margin)
                                                        (point)))))))))))))
!                     
  
  ;;;###autoload
  (defun comment-indent-new-line (&optional soft)
--- 1234,1240 ----
                               (buffer-substring (point)
                                                 (progn (move-to-left-margin)
                                                        (point)))))))))))))
! 
  
  ;;;###autoload
  (defun comment-indent-new-line (&optional soft)

bug#3371: 23.0.94; doc of `comment-style'

[Stefan Monnier]

> We probably could add two autoload cookies to newcomment.el (I don't
> recall why I wanted the one for `comment-empty-lines' once).

I'd much rather remove the one on comment-style.


        Stefan

bug#3371: 23.0.94; doc of `comment-style'

[martin rudalics]

 >> We probably could add two autoload cookies to newcomment.el (I don't
 >> recall why I wanted the one for `comment-empty-lines' once).
 >
 > I'd much rather remove the one on comment-style.

This is an option so `comment-styles' will show up anyway when people
customize `comment-style'.  Nothing won't stop people from using a
comment style you dislike personally.  The more you hide things like
`comment-styles' the more they become some sort of a forbidden fruit.

martin

bug#3371: 23.0.94; doc of `comment-style'

[Stefan Monnier]

>>> We probably could add two autoload cookies to newcomment.el (I don't
>>> recall why I wanted the one for `comment-empty-lines' once).
>> I'd much rather remove the one on comment-style.
> This is an option so `comment-styles' will show up anyway when people
> customize `comment-style'.  Nothing won't stop people from using a
> comment style you dislike personally.  The more you hide things like
> `comment-styles' the more they become some sort of a forbidden fruit.

I don't want to hide comment-styles.
I just don't like autoloading variables.

Of course, in this particular case, my favorite choice has always been
to preload newcomment.el.


        Stefan

bug#3371: 23.0.94; doc of `comment-style'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> "Style to be used for `comment-region'.
> See `comment-styles' for a list of available styles."
>
> 1. Put the available styles here.
>
> 2. There is no such function or variable as `comment-styles'.

`comment-styles' is defined in Emacs 24, at least, and has the list of
the styles.

> 3. `comment-style' is mentioned in neither the Emacs manual nor the
> Elisp manual.
>
> IOW, there is really no doc explaining what this is, what it does, or
> how it does it.

`comment-region' links to it, which I think is sufficient for people to
discover it if they want to customize `comment-region'.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#3371: 23.0.94; doc of `comment-style'

[Chong Yidong]

> > We probably could add two autoload cookies to newcomment.el (I don't
> > recall why I wanted the one for `comment-empty-lines' once).
>
> I'd much rather remove the one on comment-style.

But the comment-region docstring refers to it.