should docstrings include all defcustom options? (was: netrc field encryption in auth-source)

[Ted Zlatanov]

On Thu, 16 Jun 2011 22:28:02 +0200 Reiner Steib <address@hidden> wrote: 

RS> On Thu, Jun 16 2011, Ted Zlatanov wrote:
>> You're just listing the defcustom choices in the docstring itself.  

RS> The user should be able to figure out the valid values without jumping
RS> to the defcustom or using customize.

Is this recommended anywhere in the ELisp manual?  First time I hear
about it; it's been years since I read the whole thing end to end so
apologies if I've missed or forgotten this recommendation.

>> What if we add choices?  We have to edit the docstring again.

RS> Sure.  So what?  ;-)

It's twice the work.  For me.  And it's prone to errors, and it doesn't
convey additional information to the user.

On Thu, 16 Jun 2011 23:05:38 +0200 Lars Magne Ingebrigtsen <address@hidden> 
wrote: 

LMI> Perhaps `describe-variable' should list the customisation values and
LMI> meanings?

That would be smart.  I'd actually inline the customization interface
right in there, instead of forcing the user to follow a link in order to
customize.  Maybe as a tab or a collapsed dialog.

But all of that is besides the point of netrc field encryption...  So
I've changed the thread subject accordingly.

Ted