Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change the first line of the doc string to a complete sentence #315

Closed
mihaiolteanu opened this issue Sep 20, 2019 · 1 comment
Closed

Comments

@mihaiolteanu
Copy link

mihaiolteanu commented Sep 20, 2019

The doc string in the echo area only shows the first line of the documentation string. But that line in the case of dash functions is not a complete and standalone sentence describing what the function does so it is close to useless. Or annoying, if you will.

Example for -zip, but it is the same for all the others (i.e. line ends in mid-sentence):
screenshot1568982970

See also "Tips for Documentation Strings" in the Emacs Lisp Info pages

The first line of the documentation string should consist of one or
two complete sentences that stand on their own as a summary. ‘M-x
apropos’ displays just the first line, and if that line’s contents
don’t stand on their own, the result looks bad. In particular,
start the first line with a capital letter and end it with a
period.

For a function, the first line should briefly answer the question,
“What does this function do?” For a variable, the first line should
briefly answer the question, “What does this value mean?”

Don’t limit the documentation string to one line; use as many lines
as you need to explain the details of how to use the function or
variable. Please use complete sentences for the rest of the text
too.

@basil-conto
Copy link
Collaborator

Indeed, this breaks from a good convention for no gain. I have been slowly chiselling away at Dash docstrings, e.g. in #308, but have not yet mustered the patience or courage to fix all of them in one go. I'll eventually get around to this, but no promises as to how soon... In the meantime, feel free to submit patch(es).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants