[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Some ideas with Emacs
From: |
Michael Albinus |
Subject: |
Re: Some ideas with Emacs |
Date: |
Fri, 29 Nov 2019 21:25:48 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) |
Eli Zaretskii <address@hidden> writes:
>> >> Personally, I don't like docstring to be too verbose. Usually, when a
>> >> function is documented with both docstrings and a manual, I prefer to
>> >> put the examples in the manual.
>> >
>> > I agree: the examples should be mostly in the manual. Doc strings
>> > should only have examples if it is otherwise very hard to explain
>> > something.
>>
>> Shall we say something like this in "(elisp) Documentation Tips"?
>
> Not sure I understand what would you like to say there.
If a function is too complex to explain it in the docstring on, say one
page of ~24 lines, one shall document it more verbose in the
manual. Examples, if not necessary for understanding the docstring,
shall be shown in the manual. In such cases, there shall be a link to
the manual in the docstring.
If a function requires an exhaustive docstring, it could be an option
to break it into several functions.
Maybe all of this is too restrictive. But you see the intention.
Best regards, Michael.
- Re: Some ideas with Emacs, (continued)
- Re: Some ideas with Emacs, Stefan Kangas, 2019/11/29
- Re: Some ideas with Emacs, Emanuel Berg, 2019/11/30
- Re: Some ideas with Emacs, Stefan Monnier, 2019/11/29
- Re: Some ideas with Emacs, Michael Albinus, 2019/11/29
- Adding examples in the doc (was: Some ideas with Emacs), Stefan Monnier, 2019/11/29
- Re: Adding examples in the doc (was: Some ideas with Emacs), Yuan Fu, 2019/11/29
- Re: Adding examples in the doc, Michael Albinus, 2019/11/29
- Re: Some ideas with Emacs, Eli Zaretskii, 2019/11/29
- Re: Some ideas with Emacs, Michael Albinus, 2019/11/29
- Re: Some ideas with Emacs, Eli Zaretskii, 2019/11/29
- Re: Some ideas with Emacs,
Michael Albinus <=
- Re: Some ideas with Emacs, Eli Zaretskii, 2019/11/29
- Re: Some ideas with Emacs, Clément Pit-Claudel, 2019/11/29
- Re: Some ideas with Emacs, João Távora, 2019/11/29
- Re: Some ideas with Emacs, Yuan Fu, 2019/11/29
- Re: Some ideas with Emacs, Stefan Kangas, 2019/11/29
- Re: Some ideas with Emacs, Eli Zaretskii, 2019/11/30
- Re: Some ideas with Emacs, Eli Zaretskii, 2019/11/30
- Re: Some ideas with Emacs, Emanuel Berg, 2019/11/30
Re: Some ideas with Emacs, Anonymous, 2019/11/29
Re: Some ideas with Emacs, Stefan Monnier, 2019/11/29