Remacs: Discussion: rewrite docstrings for primitive functions

[Wilfred]

We've currently been copying docstrings exactly when we port C functions to Rust. I believe many of the C docstrings are very old, and rarely get attention. We could do better.

Here's an example of a great docstring, -reduce-from from dash.el:

Return the result of applying FN to INITIAL-VALUE and the
first item in LIST, then applying FN to that result and the 2nd
item, etc. If LIST contains no items, return INITIAL-VALUE and
FN is not called.

In the anaphoric form `--reduce-from', the accumulated value is
exposed as `acc`.

See also: `-reduce', `-reduce-r'

Good docstrings have the following properties:

• The first line is a summary. If it's short, no other information is on that line.
• They're consistently wrapped at a sensible column limit.
• They use blank lines effectively.
• They suggest other related functions where appropriate.
• They avoid abbreviation, preferring full sentences.
• They only end with (fn X Y) if they need to showing a different calling convention.

For example, here's the docstring for memql:

Return non-nil if ELT is an element of LIST.  Comparison done with `eql'.
The value is actually the tail of LIST whose car is ELT.

We can rewrite this to meet the criteria above:

Return non-nil if ELT is a member of LIST.

Elements are compared with `eq'. The return value is the tail of LIST
whose car is ELT.

See also `memql', `member'

[birkenfeld]

Actually that the reduce docstring is not really great IMO - no summary, no indication of allowed input types, what the hell is an "anaphoric form", etc.

But I agree, some Emacs docstrings can be much nicer, and "see also" suggestions would be extremely helpful for some functions whose naming scheme is... arcane.

[db48x]

I think it would be useful to encourage people to consider doing this, but not to reject patches if they don't.

On the subject of the jargon term "anaphoric form" specifically, I think it's good to keep the term around and simply explain it better, or give an example, or both. Anaphoric macros are an important but polarizing type of macro, so it's important to have the work "anaphoric" there in addition to a simpler explanation, as an educational aid to the user.

[Wilfred]

I think it would be useful to encourage people to consider doing this, but not to reject patches if they don't.

Totally agreed. I was thinking this could be a separate thing for us to encourage contributors to do.

[alphapapa]

IMO the original memql docstring is better, because it mentions the all-important test function on the first line, so it's displayed in the minibuffer. The key difference between memq,memql, and member is the test function, so that should be included on the first line.

So as a specific example, I'm not sure that's the best one to show as needing to be rewritten. :) But all of your points I generally agree with.

[shaleh]

We have fallen back on copy n paste. Time to revive this.

[shaleh]

@brotzeit perhaps we should include some commentary about this in the porting guide?

[brotzeit]

Sure. But we should make this optional.

[shaleh]

Agreed. Imagine if Emacs docstrings were more like Rust's in quality and content.

[brotzeit]

Done.