bug#35163: 25.1; `narrow-to-region' docstring no mention of args

["Basil L. Contovounesios" <contovob@tcd.ie>]

[ Your Mail-Followup-To and Mail-Copies-To headers seem wrong, they
  should point to the bug address 35163@debbugs.gnu.org instead of
  bug-gnu-emacs@gnu.org. ]

Emanuel Berg <moasenwood@zoho.eu> writes:

> Glenn Morris wrote:
>
>> (People who have particular ideas about doc
>> strings
>
> Well, I don't know about "particular", as
> I myself learned the rules from
> (checkdoc-current-buffer t) when I did Elisp
> packages. But yes, I think the rules
> make sense!

They're conventions and decent guidelines for the general case, not
rules.  Humans reserve the right to exercise their own judgement.  In
particular, the "rule" to mention positional arguments in the order they
appear often makes for unreadable docstrings IME.

Note also the relevant Elisp manual node is called "Documentation
Tips"[1], and its opening paragraph reads as follows:

> Here are some tips and conventions for the writing of documentation
> strings.  You can check many of these conventions by running the command
> ‘M-x checkdoc-minor-mode’.

[1]: (info "(elisp) Documentation Tips")

>> could save everyone a lot of time by
>> sending patches.)
>
> Should I interpret this as "one shouldn't
> bother the maintainers with details like this"?

Not at all.  Eli (amongst several other fastidious contributors) keeps
himself very busy co-maintaining Emacs, yet he still manages to set a
stellar example of how documentation should be maintained.

I'm sure what Glenn and Eli meant is closer to "a patch speaks a
thousand words," i.e. it's easier and more efficient to convey one's
intentions by showing, rather than describing, them, especially over the
lossy communication medium that is email.

> If so, I'm happy to supply patches instead,
> only I haven't done it before and don't know
> how to do it. In theory, you change the code,
> then use a tool that generates a note of the
> changes you made, and you submit that
> note, right?

Right.

> Is there some Emacs mode or infrastructure to help you with this?

There are various tools you can use.  Since Emacs uses Git as its VCS,
the built-in Version Control[2] interface and/or the third-party
Magit[3][4] package would be obvious choices if you're already somewhat
familiar with Git.

Even simpler would be to use M-x diff[5][6] or the eponymous
command-line utilities 'diff' or 'patch'.  See, for example, the manual
node on Bugs[7], particularly its subnode on Sending Patches[8].  There
is also some related information under Contributing[9] and in the
CONTRIBUTE[10] file of the Emacs source tree[11].

[2]: (info "(emacs) Version Control")
[3]: https://github.com/magit/magit/
[4]: (info "(magit) Top")
[5]: (info "(emacs) Comparing Files")
[6]: (info "(emacs) Diff Mode")
[7]: (info "(emacs) Bugs")
[8]: (info "(emacs) Sending Patches")
[9]: (info "(emacs) Contributing")
[10]: http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE
[11]: http://git.savannah.gnu.org/cgit/emacs.git/

> Also, if the docstring is in the C code, does
> that mean you have to recompile that source
> file after the change?

You only need to recompile if you want the changes to appear next time
you run the compiled Emacs instance.  You do not need to recompile in
order to create and send a patch, though compilation warnings/errors can
alert you to unforeseen problems or mistakes prior to sending the patch.

> Docstrings for C functions are themselves in the C code, right?

Yes, they are written as multiline C comments of the form /* ... */.
For details, see (info "(elisp) Writing Emacs Primitives").

> As I'm using Emacs 25, does that mean I should
> get a more recent version, for the single
> purpose of doing this? If so, which one?
> That sounds like a lot of work but thinking
> about it I suppose it doesn't have to be.

If you are interested in contributing code and/or documentation, it
would definitely be easier if you checked out the Git sources[11], if
only so that you wouldn't be looking at outdated code/documentation.

Alternatively, you can download and/or install the most recent
release[12], or download the sources via 'apt-get source'.

[12]: https://www.gnu.org/software/emacs/download.html

Emacs 26 is the current release, and it includes many fixes since Emacs
25, so I would recommend looking at something at least as recent as
26.1, if not the emacs-26 or master branches of the Git repository (I
think Emacs 26.2 is due to be released soon as well).

Thanks for your interest,

-- 
Basil