Re: Some ideas with Emacs

[Michael Albinus]

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.