From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Paul Pogonyshev Newsgroups: gmane.emacs.devel Subject: Re: maphash: improve docstring Date: Sat, 2 Apr 2016 14:13:57 +0200 Message-ID: References: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary=001a113e1bd419d799052f7f6eaf X-Trace: ger.gmane.org 1459599255 18276 80.91.229.3 (2 Apr 2016 12:14:15 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 2 Apr 2016 12:14:15 +0000 (UTC) Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Apr 02 14:14:15 2016 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 1amKRS-0002mu-Ow for ged-emacs-devel@m.gmane.org; Sat, 02 Apr 2016 14:14:15 +0200 Original-Received: from localhost ([::1]:49285 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1amKRS-0003lJ-5C for ged-emacs-devel@m.gmane.org; Sat, 02 Apr 2016 08:14:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38715) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1amKRD-0003l2-TG for emacs-devel@gnu.org; Sat, 02 Apr 2016 08:14:00 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1amKRC-0001fH-O7 for emacs-devel@gnu.org; Sat, 02 Apr 2016 08:13:59 -0400 Original-Received: from mail-oi0-x234.google.com ([2607:f8b0:4003:c06::234]:35583) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1amKRC-0001fB-H9 for emacs-devel@gnu.org; Sat, 02 Apr 2016 08:13:58 -0400 Original-Received: by mail-oi0-x234.google.com with SMTP id p188so108099947oih.2 for ; Sat, 02 Apr 2016 05:13:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc; bh=tEQ1w4bQ1RWkVCJMyEXGVGLRvVWDUxVavK9vYrjDa+g=; b=WVoZ0BnQ6iZk7qjxQy4CeAD3aGs9SAqV6zqjD7JimNv1w4SPVL9lApgkqGTfTD2cWd 7TWw+VpPvrxW0bgQJ0Z2c9FcF1r2vQjBSCumH6L1+dzZhgHTduAez2c42pNPTq9e9GTM NLw1bRhMNXQtdQPqBI2EdplbHj8Yo2A6Q0VZ69DVQPB9anIyfQS2vx0OCWIlLa3t1QeD zHebtDs/UebN3Jl9CeAXOsR7S6tTnSK8kc2n0mBOVb2kYnhqDqCvGAanzfejYpoml/Hr xGnWoxU8ipgsYbGVesBAhtEevynCSP1a9YP0JChrXMYe89SIvD8ag9Z55vBs2XYv56F6 vgOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:date :message-id:subject:from:to:cc; bh=tEQ1w4bQ1RWkVCJMyEXGVGLRvVWDUxVavK9vYrjDa+g=; b=H8iRCETH9AwEzPKJeyjCn2YLGqKJWtBgdtbDFBjvDPa15T6IRRM/FLK05D/PJREwDe FcLklgg+M33yhR5KC74Jh5GLLtQAMldh+dhQmuLRggIB42YrocnC9srscYxa180Q8Wta tDm5YLqSCy39Qzwt7BzvtCt2QbLKnuTNVzTmDyWuUGoiwn0cbwRw6nwwZ2/q9rUq7K0a mL2c63745yzwQKHHw2zPG4nvK/xLnEXzAPK5X2AhUy8MdGqZk2/ieQaGbYCaWvpLOj8u MLANxoPurUSuO+sr+LqfjPVVbALW1NAqr/FaMgD+28YUbxPMOm4SiDUUt9Qu3tA9CDIL vAlg== X-Gm-Message-State: AD7BkJL+2WE7uOWlrKcaRbDDRunFXHJ1T7VyMx6cbuA2P0J9sBAvzgTbcRNrp1r3JBT33QmNRgvIFsI1OOCauA== X-Received: by 10.157.20.161 with SMTP id d30mr8228799ote.165.1459599238034; Sat, 02 Apr 2016 05:13:58 -0700 (PDT) Original-Received: by 10.202.197.148 with HTTP; Sat, 2 Apr 2016 05:13:57 -0700 (PDT) In-Reply-To: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2607:f8b0:4003:c06::234 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:202592 Archived-At: --001a113e1bd419d799052f7f6eaf Content-Type: text/plain; charset=UTF-8 How about the following patch? Paul * src/fns.c (Fmaphash): Add reference to the corresponding Info node to the docstring. * doc/lispref/hash.texi (Hash Access): Expand documentation of 'maphash' with detailed description of what happens if 'function' modifies the 'table'. On 30 March 2016 at 00:44, Stefan Monnier wrote: >> Could one expand documentation of `maphash' like this? I'm not sure >> it follows from what you wrote, but I understood it like this: > > That looks right. > >> Call FUNCTION for all entries in hash table TABLE. >> FUNCTION is called with two arguments, KEY and VALUE. >> `maphash' always returns nil. >> FUNCTION will usually just inspect its arguments, but may also >> alter TABLE and this will not cause `maphash' to malfunction. >> However, some effects are not fully defined, see below. >> If FUNCTION adds an entry to TABLE, it may or may not be called >> with the added key/value pair. >> If FUNCTION changes value already associated with a key and it >> has not been called with that key yet, it will be called with key >> and the new value during the iteration later. Otherwise it will >> not be called for that key again. >> If FUNCTION removes a key and it has not been called with it yet, >> it will not be called for the removed key in the future either. >> Note that if FUNCTION removes or changes value only for KEY it is >> called with, the behavior is completely defined. > > Yes. I think we can come up with something more concise (by splitting > the description of which keys will be called, from the description of > which value is passed), but haven't been very successful at it either. > >> Another option is to add this (probably with more explanation) to >> the manual and add just a sentence to the tune of "see manual for >> details" to the docstring. > > Sure, > > > Stefan --001a113e1bd419d799052f7f6eaf Content-Type: text/plain; charset=US-ASCII; name="maphash-doc.diff" Content-Disposition: attachment; filename="maphash-doc.diff" Content-Transfer-Encoding: base64 X-Attachment-Id: f_imj3p3ld0 ZGlmZiAtLWdpdCBhL2RvYy9saXNwcmVmL2hhc2gudGV4aSBiL2RvYy9saXNwcmVmL2hhc2gudGV4 aQppbmRleCBhMTk3Mzk5Li42MTEyMjVjIDEwMDY0NAotLS0gYS9kb2MvbGlzcHJlZi9oYXNoLnRl eGkKKysrIGIvZG9jL2xpc3ByZWYvaGFzaC50ZXhpCkBAIC0yMjUsNiArMjI1LDI3IEBAIFRoaXMg ZnVuY3Rpb24gY2FsbHMgQHZhcntmdW5jdGlvbn0gb25jZSBmb3IgZWFjaCBvZiB0aGUgYXNzb2Np YXRpb25zIGluCiBAdmFye3RhYmxlfS4gIFRoZSBmdW5jdGlvbiBAdmFye2Z1bmN0aW9ufSBzaG91 bGQgYWNjZXB0IHR3bwogYXJndW1lbnRzLS0tYSBAdmFye2tleX0gbGlzdGVkIGluIEB2YXJ7dGFi bGV9LCBhbmQgaXRzIGFzc29jaWF0ZWQKIEB2YXJ7dmFsdWV9LiAgQGNvZGV7bWFwaGFzaH0gcmV0 dXJucyBAY29kZXtuaWx9LgorCitUeXBpY2FsbHksIEB2YXJ7ZnVuY3Rpb259IHdpbGwganVzdCBp bnNwZWN0IGl0cyBhcmd1bWVudHMuICBIb3dldmVyLAoraXQgaXMgYWxzbyBhbGxvd2VkIHRvIHJl YWQgYW5kL29yIG1vZGlmeSBAdmFye3RhYmxlfSwgZXZlbiBmb3IKK3VucmVsYXRlZCBrZXlzLiAg VGhpcyB3aWxsIG5vdCBjYXVzZSBAY29kZXttYXBoYXNofSB0byBtYWxmdW5jdGlvbiwKK2J1dCBz b21lIGVmZmVjdHMgYXJlIG5vdCBmdWxseSBkZWZpbmVkLCBhcyBkZXNjcmliZWQgYmVsb3cuCisK K0lmIEB2YXJ7ZnVuY3Rpb259IGFkZHMgYSBuZXcgZW50cnkgdG8gdGhlIEB2YXJ7dGFibGV9LCBp dCBAZW1waHttYXkgb3IKK21heSBub3R9IGJlIGNhbGxlZCBkdXJpbmcgdGhpcyBpdGVyYXRpb24g d2l0aCB0aGUgbmV3IGtleS92YWx1ZSBwYWlyLgorCitJZiBAdmFye2Z1bmN0aW9ufSBjaGFuZ2Vz IHRoZSB2YWx1ZSBhbHJlYWR5IGFzc29jaWF0ZWQgd2l0aCBhIGtleQorQHZhcntLfSBhbmQgaXQg aGFzIG5vdCBiZWVuIGNhbGxlZCB3aXRoIEB2YXJ7S30geWV0LCBpdCB3aWxsIGJlIGNhbGxlZAor d2l0aCB0aGUgQHZhcntLfSBhbmQgdGhlIEBlbXBoe25ld30gdmFsdWUgZHVyaW5nIHRoZSBpdGVy YXRpb24gbGF0ZXIuCitPdGhlcndpc2UgaXQgd2lsbCBub3QgYmUgY2FsbGVkIGZvciBAdmFye0t9 IGFnYWluLCBldmVuIHRob3VnaCBpdCBoYXMKK2JlZW4gY2FsbGVkIHdpdGggdGhlIG9sZCB2YWx1 ZSBiZWZvcmUuCisKK0lmIEB2YXJ7ZnVuY3Rpb259IHJlbW92ZXMgYSBrZXkgYW5kIGl0IGhhcyBu b3QgYmVlbiBjYWxsZWQgd2l0aCBpdAoreWV0LCBpdCB3aWxsIG5vdCBiZSBjYWxsZWQgZm9yIHRo ZSByZW1vdmVkIGtleSBpbiB0aGUgZnV0dXJlIGVpdGhlci4KKworSW4gcGFydGljdWxhciwgaXQg Zm9sbG93cyB0aGF0IGlmIEB2YXJ7ZnVuY3Rpb259IHJlbW92ZXMgb3IgY2hhbmdlcwordmFsdWUg b25seSBmb3IgdGhlIEB2YXJ7a2V5fSBpdCBpcyBjYWxsZWQgd2l0aCwgdGhlIGJlaGF2aW9yIGlz Citjb21wbGV0ZWx5IGRlZmluZWQuCiBAZW5kIGRlZnVuCiAKIEBub2RlIERlZmluaW5nIEhhc2gK ZGlmZiAtLWdpdCBhL3NyYy9mbnMuYyBiL3NyYy9mbnMuYwppbmRleCA4MjVlNDQzLi42NWQ0NmY3 IDEwMDY0NAotLS0gYS9zcmMvZm5zLmMKKysrIGIvc3JjL2Zucy5jCkBAIC00NzE1LDcgKzQ3MTUs MTAgQEAgREVGVU4gKCJyZW1oYXNoIiwgRnJlbWhhc2gsIFNyZW1oYXNoLCAyLCAyLCAwLAogREVG VU4gKCJtYXBoYXNoIiwgRm1hcGhhc2gsIFNtYXBoYXNoLCAyLCAyLCAwLAogICAgICAgIGRvYzog LyogQ2FsbCBGVU5DVElPTiBmb3IgYWxsIGVudHJpZXMgaW4gaGFzaCB0YWJsZSBUQUJMRS4KIEZV TkNUSU9OIGlzIGNhbGxlZCB3aXRoIHR3byBhcmd1bWVudHMsIEtFWSBhbmQgVkFMVUUuCi1gbWFw aGFzaCcgYWx3YXlzIHJldHVybnMgbmlsLiAgKi8pCitgbWFwaGFzaCcgYWx3YXlzIHJldHVybnMg bmlsLgorCitGVU5DVElPTiBtYXkgbW9kaWZ5IHRoZSBUQUJMRSBldmVuIGFzIGl0ZXJhdGlvbiBp cyBpbiBwcm9ncmVzcy4KK1NlZSBJbmZvIG5vZGUgYChlbGlzcClIYXNoIEFjY2VzcycgZm9yIGRl dGFpbHMuICAqLykKICAgKExpc3BfT2JqZWN0IGZ1bmN0aW9uLCBMaXNwX09iamVjdCB0YWJsZSkK IHsKICAgc3RydWN0IExpc3BfSGFzaF9UYWJsZSAqaCA9IGNoZWNrX2hhc2hfdGFibGUgKHRhYmxl KTsK --001a113e1bd419d799052f7f6eaf--