* RE: public APIs and private ones (Re: `C-h v' may offer too manysymbols)
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
@ 2011-03-11 5:41 ` Drew Adams
2011-03-11 19:08 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Ted Zlatanov
2011-03-11 20:28 ` Stefan Monnier
2 siblings, 0 replies; 9+ messages in thread
From: Drew Adams @ 2011-03-11 5:41 UTC (permalink / raw)
To: 'Kenichi Handa', 'Stefan Monnier'
Cc: lekktu, tzz, emacs-devel
> shouldn't we have a way to distinguish functions/macros/
> variables for public API from those for internal (i.e. only
> within a specific package) use only.
I have no problem with that in principle. From my point of view, "internal"
here would be something definable (e.g. declarable) by the coder.
IOW, it has no intrinsic meaning; it can only be defined by someone, in some
context, with some purpose. Its only value is relative to those things.
It expresses the coder's intention that most users will probably not want or
need to use the stuff designated "internal" most of the time. Nothing more than
that.
> For instance, as basic-save-buffer-1 is just a helper function
> of basic-save-buffer, there's no need to list it by C-h f TAB.
I sure disagree here. "No need" isn't something the coder can decide. "You
probably aren't very interested in this" is different from "you don't need
this".
Personally, I want `C-h f' to include all functions as candidates. This is
`describe-function', not `describe-user-function' or some such.
I have no problem with someone adding a new command to do what you describe. I
would prefer that it not be bound to `C-h f', but that's another matter (and I
certainly wouldn't go to the barricades about it).
Or a prefix arg might be acceptable for distinguishing the two. Then we would
be arguing only over the default behavior (behavior with no prefix arg).
But my personal preference, used in my own version of `C-h f', is for a prefix
arg to mean use only _commands_ as completion candidates. Perhaps a distinction
via different prefix-arg values would be appropriate: all functions, only
commands, only "external" functions.
> In addition, and this is more important, such a
> distinguishment makes it easier to maintain a package. For
> instance, when I improve the MIME handling of rmailmm.el,
> the most difficult thing was to keep backward compatibility
> of existing functions. It seems that most of them are
> intended for internal use only. If that is clear, I could
> have renamed or changed the behaviour of some of them.
Again, "internal" means nothing (especially) for a language like Lisp
(especially a Lisp that has no packages/modules), other than as an expression of
a coder's intention. That's not nothing, of course. And there's nothing wrong
with expressing such an intention - it can be helpful. But "internal" can (and
should) never be more than that: expression of intended use by most users in
most situations.
People are users at different levels at different times or in different
contexts. Something is language in one context and metalanguage in another
context. Same with internal and external. One person's or one context's
internal is another person's or another context's external.
That does not mean that such terms are meaningless or useless; it just means
that they are far from absolute. Sooner or later someone (and not only the
maintainer) will want to use "internal" functions for something - possibly
something "external" or unintended originally. Code manipulation (by code) is
just one example.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: public APIs and private ones (Re: `C-h v' may offer too many symbols)
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
2011-03-11 5:41 ` public APIs and private ones (Re: `C-h v' may offer too manysymbols) Drew Adams
@ 2011-03-11 19:08 ` Ted Zlatanov
2011-03-11 20:28 ` Stefan Monnier
2 siblings, 0 replies; 9+ messages in thread
From: Ted Zlatanov @ 2011-03-11 19:08 UTC (permalink / raw)
To: emacs-devel
On Fri, 11 Mar 2011 13:31:30 +0900 Kenichi Handa <handa@m17n.org> wrote:
KH> In article <jwv7hc6e7dg.fsf-monnier+emacs@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> > Yes, it is a bit silly complete keywords, which are not variables by
>> > definition. I'm going to install this trivial fix.
>> Sounds good. FWIW, here's a patch I have pending for the lexbind branch
>> (where special-variable-p is t only for vars that have been defvar'd
>> or defconst'd).
KH> This is a little bit different topic, but shouldn't we have
KH> a way to distinguish functions/macros/variables for public
KH> API from those for internal (i.e. only within a specific
KH> package) use only. For instance, as basic-save-buffer-1 is
KH> just a helper function of basic-save-buffer, there's no need
KH> to list it by C-h f TAB.
KH> In addition, and this is more important, such a
KH> distinguishment makes it easier to maintain a package. For
KH> instance, when I improve the MIME handling of rmailmm.el,
KH> the most difficult thing was to keep backward compatibility
KH> of existing functions. It seems that most of them are
KH> intended for internal use only. If that is clear, I could
KH> have renamed or changed the behaviour of some of them.
I think (or autoloaded-p called-interactively-p) functions are
implicitly intended for public consumption so maybe that's the criteria
you're looking for (I'm inventing some of these predicate names).
But maybe it also makes sense to add filtering by `autoloaded-p' and
`called-interactively-p' (which is currently available with M-x TAB) and
`has-docstring-p' to `C-h f' somehow, either by making parallel commands
or by adding filtering inside it. So then public-API-p can be part of
that system, if it's different from (or autoloaded-p called-interactively-p).
Ted
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: public APIs and private ones (Re: `C-h v' may offer too many symbols)
2011-03-11 4:31 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Kenichi Handa
2011-03-11 5:41 ` public APIs and private ones (Re: `C-h v' may offer too manysymbols) Drew Adams
2011-03-11 19:08 ` public APIs and private ones (Re: `C-h v' may offer too many symbols) Ted Zlatanov
@ 2011-03-11 20:28 ` Stefan Monnier
2 siblings, 0 replies; 9+ messages in thread
From: Stefan Monnier @ 2011-03-11 20:28 UTC (permalink / raw)
To: Kenichi Handa; +Cc: lekktu, tzz, emacs-devel
> This is a little bit different topic, but shouldn't we have
> a way to distinguish functions/macros/variables for public
> API from those for internal (i.e. only within a specific
> package) use only.
I try to follow the convention that I use "<package>--" for
functions/macros/variables internal to <package>. It's just
a convention and it's currently very little used, but I encourage people
to use it more systematically.
We also use the "internal-" prefix for things that are "internal to
Emacs core" (typically functions exported from C meant only for use in
subr.el, tho I also used it in lexbind for operations that only appear
in some intermediate form of the code manipulated by the compiler).
> For instance, as basic-save-buffer-1 is just a helper function of
> basic-save-buffer, there's no need to list it by C-h f TAB.
I'm not completely sure if it would be a good idea: I also use C-h f to
find such internal functions.
> In addition, and this is more important, such a distinguishment makes
> it easier to maintain a package.
Fully agreed. It also makes it easier for users of the package to
figure out what are the intended entry points.
Stefan
^ permalink raw reply [flat|nested] 9+ messages in thread