From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: maphash: improve docstring Date: Tue, 29 Mar 2016 18:44:59 -0400 Message-ID: References: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1459291535 19985 80.91.229.3 (29 Mar 2016 22:45:35 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 29 Mar 2016 22:45:35 +0000 (UTC) Cc: emacs-devel@gnu.org To: Paul Pogonyshev Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Mar 30 00:45:26 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 1al2O4-0002PY-65 for ged-emacs-devel@m.gmane.org; Wed, 30 Mar 2016 00:45:24 +0200 Original-Received: from localhost ([::1]:50331 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1al2O3-0007xh-42 for ged-emacs-devel@m.gmane.org; Tue, 29 Mar 2016 18:45:23 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43703) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1al2Nm-0007xI-UP for emacs-devel@gnu.org; Tue, 29 Mar 2016 18:45:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1al2Nh-0002Qw-V4 for emacs-devel@gnu.org; Tue, 29 Mar 2016 18:45:06 -0400 Original-Received: from ironport2-out.teksavvy.com ([206.248.154.181]:13579) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1al2Nh-0002Qq-Q1 for emacs-devel@gnu.org; Tue, 29 Mar 2016 18:45:01 -0400 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: A0A2FgA731xV/6ORWxdcgxCEAoVVwwsEAgKBPDwRAQEBAQEBAYEKQQWDXQEBAwFWIwULCzQSFBgNJIg3CM8jAQEBAQYCAR+LOoUFB4QtBZA0pFAjggkdgW4igngBAQE X-IPAS-Result: A0A2FgA731xV/6ORWxdcgxCEAoVVwwsEAgKBPDwRAQEBAQEBAYEKQQWDXQEBAwFWIwULCzQSFBgNJIg3CM8jAQEBAQYCAR+LOoUFB4QtBZA0pFAjggkdgW4igngBAQE X-IronPort-AV: E=Sophos;i="5.13,465,1427774400"; d="scan'208";a="202827776" Original-Received: from 23-91-145-163.cpe.pppoe.ca (HELO pastel.home) ([23.91.145.163]) by ironport2-out.teksavvy.com with ESMTP; 29 Mar 2016 18:45:00 -0400 Original-Received: by pastel.home (Postfix, from userid 20848) id E7EF863FC5; Tue, 29 Mar 2016 18:44:59 -0400 (EDT) In-Reply-To: (Paul Pogonyshev's message of "Tue, 29 Mar 2016 20:58:24 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 206.248.154.181 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:202424 Archived-At: > 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