From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: =?UTF-8?B?UHJ6ZW15c8WCYXcgV29qbm93c2tp?= Newsgroups: gmane.emacs.devel Subject: Re: How to find when a function/var has been added Date: Sat, 08 Aug 2015 09:37:59 +0200 Message-ID: <55C5B1D7.2010700@cumego.com> References: <55C25834.3020305@cumego.com> <83si7xsfjx.fsf@gnu.org> <55C279B0.5040708@cumego.com> <86egjgaga0.fsf@stephe-leake.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1439019519 24997 80.91.229.3 (8 Aug 2015 07:38:39 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 8 Aug 2015 07:38:39 +0000 (UTC) To: Stephen Leake , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Aug 08 09:38:30 2015 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1ZNyi5-0007R1-Ds for ged-emacs-devel@m.gmane.org; Sat, 08 Aug 2015 09:38:29 +0200 Original-Received: from localhost ([::1]:52166 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZNyi4-0007wl-Gq for ged-emacs-devel@m.gmane.org; Sat, 08 Aug 2015 03:38:28 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53540) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZNyi1-0007tY-1X for emacs-devel@gnu.org; Sat, 08 Aug 2015 03:38:26 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZNyhj-0005NM-4z for emacs-devel@gnu.org; Sat, 08 Aug 2015 03:38:24 -0400 Original-Received: from smtp20.iq.pl ([86.111.242.225]:54146) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZNyhi-0005Je-OU for emacs-devel@gnu.org; Sat, 08 Aug 2015 03:38:06 -0400 Original-Received: (qmail 12895 invoked from network); 8 Aug 2015 07:38:00 -0000 Original-Received: from unknown (HELO [192.168.1.106]) (esperanto@cumego.com@[77.255.102.39]) (envelope-sender ) by smtp22.iq.pl with AES128-SHA encrypted SMTP for ; 8 Aug 2015 07:38:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.8.0 In-Reply-To: <86egjgaga0.fsf@stephe-leake.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 86.111.242.225 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:188598 Archived-At: >> 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.