From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Date: Tue, 30 Nov 2010 20:10:36 -0800 Message-ID: References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com><27E6B536A09248629C372671995E7E97@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1291197187 11929 80.91.229.12 (1 Dec 2010 09:53:07 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 1 Dec 2010 09:53:07 +0000 (UTC) Cc: 7509@debbugs.gnu.org To: "'Stefan Monnier'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Dec 01 10:53:03 2010 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1PNjMx-0001d3-RB for geb-bug-gnu-emacs@m.gmane.org; Wed, 01 Dec 2010 10:53:01 +0100 Original-Received: from localhost ([127.0.0.1]:48973 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PNjMx-00068K-8U for geb-bug-gnu-emacs@m.gmane.org; Wed, 01 Dec 2010 04:52:59 -0500 Original-Received: from [140.186.70.92] (port=43241 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PNe6P-0006RX-QH for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2010 23:15:57 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PNe64-0000Ni-9z for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2010 23:15:33 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:51878) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PNe64-0000NU-8A for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2010 23:15:12 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1PNdy9-00062z-Qh; Tue, 30 Nov 2010 23:07:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 01 Dec 2010 04:07:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129117641623231 (code B ref 7509); Wed, 01 Dec 2010 04:07:01 +0000 Original-Received: (at 7509) by debbugs.gnu.org; 1 Dec 2010 04:06:56 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNdy3-00062e-SN for submit@debbugs.gnu.org; Tue, 30 Nov 2010 23:06:56 -0500 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNdy1-00062R-N1 for 7509@debbugs.gnu.org; Tue, 30 Nov 2010 23:06:54 -0500 Original-Received: from rcsinet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id oB14CTIG005501 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 1 Dec 2010 04:12:30 GMT Original-Received: from acsmt355.oracle.com (acsmt355.oracle.com [141.146.40.155]) by rcsinet13.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id oB14C4d7019760; Wed, 1 Dec 2010 04:12:04 GMT Original-Received: from abhmt006.oracle.com by acsmt354.oracle.com with ESMTP id 829726541291176635; Tue, 30 Nov 2010 20:10:35 -0800 Original-Received: from dradamslap1 (/10.159.216.81) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 30 Nov 2010 20:10:34 -0800 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcuRA3QpXinHB3TlTV2fzRxb7y44OwACAGQg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Tue, 30 Nov 2010 23:07:01 -0500 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:42047 Archived-At: > > Also, it wouldn't hurt to include such tiny diagrams in the > > doc string for `comment-styles' (esp. since it is a defconst). > > In this case, a set of pictures is worth more than a set of > > one-liner descriptions. > > Again, that would amount to documenting the particular > current value of that variable, rather than the set of > possible values and their meaning. No, we would be documenting the _default_ value. Nothing wrong with that. It serves as a model, a particular value, yes, but also a good example. And the value that defines the behavior (the possibilities) out of the box - good to know. Both understanding the default behavior/value and having it as a model are useful. > So that would be wrong. Such documentation can't belong to > comment-styles's docstring; only to the doc of each style > defined there. Either nothing is defined there (it's just one possible value, as you point out) or everything is defined there (it's the default value, defining all the behavior possibilities you get if you don't change anything). You cannot have it both ways. ;-) I'd say that we should describe the default value in the doc string (and not just inside the value itself), because I think that will help users. The doc string just needs to make clear that this description applies to the _default value_, which serves as _an example_. No matter how good the one-liner descriptions we might come up with, they are no match for the little samples you sent me. Once you see them it's all clear, but until then a reader is really only guessing. IMO. > > BTW, why are all of the various possibilities (align, > > extra, box etc.) defined only for indented comments? > > The only reason `plain' exists is because that's what was used in > Emacs=22. I strongly discourage people from using it since it often > results in comments that aren't properly indented. I strongly prefer `plain'. ;-) But I don't program in C. And I don't pretend to speak for anyone but myself. > > plain - Start in column 0 (do not indent) > > indent - Full comment per line, ends not aligned > > aligned - Full comment per line, ends aligned > > box - Full comment per line, ends aligned, + top and bottom > > extra-line - One comment for all lines, end on a line by itself > > multi-line - One comment for all lines, end on last commented line > > box-multi - One comment for all lines, + top and bottom > > Thanks, that seems much better than what I have now. You're welcome. Thanks for making the changes.