Getting functions usage examples [Was: Re: Knowing where a function has been used (e.g. for optimizing) [Was: Re: Optimising Elisp code]]

[Garreau, Alexandre]

On 2018-10-07 at 14:41, Emanuel Berg wrote:
> Garreau, Alexandre wrote:
>
>> (examples are the other
>> great way of learning: inherenthly more
>> imperfect than a definition but quicker and
>> easier)
>
> There should always first be the definition,

Agree.  Yet sometimes people are bad at abstraction, so when the
abstraction grow complex, in order to *more easily* understand the
example, after one trye, one can begin by getting a guess of what it
does, through an example (with a context, of course, because
side-effects (and imperative programming generally) and complex data
stractures), and then come back at the definition.

> then one simple example, then a more
> complicated example, then the example that
> confirms the rule.

as not everybody needs examples, and ideally we should just keep using
only definitions, nobody (we hope) will waste a lot of precious time
putting 2-3 call examples in the docstrings (especially if it’s
something complex so for each you need to describe a valid context).

Since the function is only dynamically typed, unless you begin
inference-typing or basing on symbols names, you will have a hard time
at automatically generating the simplest meaningful examples.

So having a grasp of “how is this function used in reality” may be quite
useful… and *then*, afterwards, someone could try something more
complex, intuitive and experimental, such as of these (potentially
thousands, or more) examples, automatically sorting out the most simple,
the most idiomatics, the better ones.

Then of course I get this may go from quite straightforward for one
special library function used one or three times around, to grow
especially complex as for “list of functions where `+' / `point' /
`progn' is used”.

And, regard to optimization, again, for these examples (the most used
functions), if one got automatically inlined, then it would require too
much recompiling, then the compiler might figure out it shouldn’t inline
it (unless the programmer accept to do so (maybe it could suggests her
about it (wrt its magnitude of usage through the rest of emacs)?)).