Re: How to find when a function/var has been added

[Stephen Leake]

Przemysław Wojnowski <address@hidden> writes:

>> And it will be very
>> easy to forget to change it on a later edit; no information is one
>> thing, wrong information is worse.
> I don't get this one. To change "Since: x" on later edit? Why?

If the arg list or semantics of the function changes, the version in
which that happens should be noted.

On the other hand, we really try to avoid such changes in Emacs core, so
this may not be much of a problem. It is more of a problem in ELPA
packages.

>>> but may
>>> make life much easier to its users.
>>
>> I guess we disagree on that.
>>
>> In particular, it is only useful for a very small subset of
>> functions/variables. The ones that you happen to need are useful, but
>> there's no way to know in advance which ones that will be.

> Clearly we disagree here.
> IMHO it is useful to any programmer that would like to write an Emacs
> package that works across some emacsen. For such people Emacs is a
> programming platform that can be deployed in different versions (API
> versions - in case of Emacs different libs/functions/vars). Having
> "Since: x" makes it faster learn and hence to write software that
> works on different versions of the platform.

I misspoke; it would be useful information to have. But the cost of
providing it, at least with the mechanism you propose, is too high, for
a volunteer project like Emacs. Especially since there are other
reasonable ways to get the same information.

My point is that there are a _lot_ of functions in Emacs, and any given
project uses a _very_ small subset of them. So the cost/benefit ratio is
inherently skewed towards low benefit.

> For example Jira is such a platform. It may be installed in different
> versions, and a programmer that writes Jira plugins needs to know
> which classes/methods/vars can be used safely for a plugin.

What mechanism do they use to document this information? And how much
money do they spend doing that?

Another example is Google Android; every function has "added in API nn"
annotation in the html docs. I have no idea how they generate that.

But Google has lots of money to pay programmers to produce that info,
and they have a strong compatibility goal; they want people to write
code that can run on many different versions of the Android platform.

Emacs has neither the money, nor the strong compatibility goal (the latter
partly because of the former, of course).

>> I like Eli's 'git annotate' solution;
>> that's an automated way to get mostly what you are asking for.
>>
>> It needs another step; relating a git hash to an Emacs version. I hope
>> there's a git function that takes a hash and two tags and tells you if
>> the hash occured between them.

> You missed the step where a programmer have to download sources of the 
> platform
> just to find out whether a function can be used, when targeting some version
> of the platform.

Yes, But "git clone" is fast enough; that is just part of the cost of
writing multi-version code.

In general, the lack of this kind of detailed documentation is part of
the cost of using open-source software developed by volunteers. 

-- 
-- Stephe