You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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):
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.
The text was updated successfully, but these errors were encountered:
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).
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):See also "Tips for Documentation Strings" in the Emacs Lisp Info pages
The text was updated successfully, but these errors were encountered: