[Emacs-diffs] emacs-25 c2ba4a2: ; Added documentation for undo-auto functionality.

[Emacs-diffs] emacs-25 c2ba4a2: ; Added documentation for undo-auto functionality.

[Eli Zaretskii]

This commit documents internal functions and variables.  IMO, if we
think they deserve being documented (and I think I agree), they
shouldn't be internal in the first place.

WDYT?

Thanks.

Re: [Emacs-diffs] emacs-25 c2ba4a2: ; Added documentation for undo-auto functionality.

[John Wiegley]

<#secure method=pgpmime mode=sign>
>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> This commit documents internal functions and variables. IMO, if we think
> they deserve being documented (and I think I agree), they shouldn't be
> internal in the first place.

If they're truly internal, I don't think they should be documented in
elisp.texi. Sufficient documentation is provided for such functions via the
docstring.

If one feels they do belong in elisp.texi, they shouldn't be internal, as Eli
indicates.

In a sense, elisp.texi defines our "Emacs Lisp API" to programmers, so
anything we document there represent a certain level of commitment.




-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: [Emacs-diffs] emacs-25 c2ba4a2: ; Added documentation for undo-auto functionality.

[Phillip Lord]

John Wiegley <jwiegley@gmail.com> writes:

> <#secure method=pgpmime mode=sign>
>>>>>> Eli Zaretskii <eliz@gnu.org> writes:
>
>> This commit documents internal functions and variables. IMO, if we think
>> they deserve being documented (and I think I agree), they shouldn't be
>> internal in the first place.
>
> If they're truly internal, I don't think they should be documented in
> elisp.texi. Sufficient documentation is provided for such functions via the
> docstring.
>
> If one feels they do belong in elisp.texi, they shouldn't be internal, as Eli
> indicates.
>
> In a sense, elisp.texi defines our "Emacs Lisp API" to programmers, so
> anything we document there represent a certain level of commitment.


Yeah, think that's true. I made them internal but then when I was
writing the documentation thought perhaps they should be documented.
Deciding what is "end-user" functionality and what is "implementation"
gets a bit hard when you are talking about code of this form.

I'll patch them up and make these two non internal.

Phil

Re: [Emacs-diffs] emacs-25 c2ba4a2: ; Added documentation for undo-auto functionality.

[Stefan Monnier]

> Deciding what is "end-user" functionality and what is "implementation"
> gets a bit hard when you are talking about code of this form.

When in doubt, I recommend to err on the side of not documenting.


        Stefan

Re: [Emacs-diffs] emacs-25 c2ba4a2: ; Added documentation for undo-auto functionality.

[Phillip Lord]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Deciding what is "end-user" functionality and what is "implementation"
>> gets a bit hard when you are talking about code of this form.
>
> When in doubt, I recommend to err on the side of not documenting.

I think in this case, the function and variable should probably not be
internal. The undo-auto-amalgamate function in particular, might well be
of use outside.

Phil