Re: [PATCH] emacs: remove hardcoded defaults values from docstrings

Subject: Re: [PATCH] emacs: remove hardcoded defaults values from docstrings

Date: Tue, 04 Jun 2013 11:22:29 -0300

To: Austin Clements

Cc: Tomi Ollila, notmuch@notmuchmail.org

From: David Bremner


Austin Clements <amdragon@MIT.EDU> writes:
>
> Right.  I think we should both reference the variable and say what the
> default behavior is (there's no reason not to do both).  But isn't
> that what these docstrings used to do?

Looking at the old docstrings in notmuch-show.el, I agree they basically
implement Tomi's suggestion.  While I think copying default values of
variables into docstrings creates some minor maintainability traps
(since we then need to remember to look at all the places a variable is
referenced if we change the default value), I'm willing to revert the
patch if people think the tradeoff of better usability is worth it.

It is unfortunate emacs doesn't provide a way to expand the current
value of a variable in the help string, but there we are. It probably
wouldn't be as easy to understand as hand crafted text in any case.

d


Thread: