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

["Przemysław Wojnowski" <esperanto@cumego.com>]

>> Adding simple "Since: x" to a doc is not very time consuming,
>
> Not for one doc, but it adds up _very_ quickly.
So it's good that "Since: x" adds up. It only means that number of documented
functions/vars is growing.
Maybe it could be generated and added, at the end of each docstring, by some
script that goes through git history and/or Changelog/NEWS and gets Emacs
version from there.

> 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?

>> 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.

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.
Nobody expects such programmer to grep Jira's git history just to find it out.
It's just counterproductive.
When a company is developing a platform (say Jira) it makes programming on it
as easy as possible. Similar mindset is useful in non-commercial software too.

> 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.