From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Paul Pogonyshev Newsgroups: gmane.emacs.devel Subject: generator documentation improvement Date: Wed, 8 Mar 2017 21:47:43 +0100 Message-ID: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary=001a113cdfe88c0205054a3e3d26 X-Trace: blaine.gmane.org 1489006087 14963 195.159.176.226 (8 Mar 2017 20:48:07 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 8 Mar 2017 20:48:07 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Mar 08 21:47:56 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cliUz-0002Wp-95 for ged-emacs-devel@m.gmane.org; Wed, 08 Mar 2017 21:47:53 +0100 Original-Received: from localhost ([::1]:58390 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cliV1-0006FX-KN for ged-emacs-devel@m.gmane.org; Wed, 08 Mar 2017 15:47:55 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43028) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cliUu-0006FP-DF for emacs-devel@gnu.org; Wed, 08 Mar 2017 15:47:49 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cliUt-0003I6-CF for emacs-devel@gnu.org; Wed, 08 Mar 2017 15:47:48 -0500 Original-Received: from mail-oi0-x22a.google.com ([2607:f8b0:4003:c06::22a]:36568) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cliUt-0003Hw-5E for emacs-devel@gnu.org; Wed, 08 Mar 2017 15:47:47 -0500 Original-Received: by mail-oi0-x22a.google.com with SMTP id 126so26526083oig.3 for ; Wed, 08 Mar 2017 12:47:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:from:date:message-id:subject:to; bh=LpAgbHbn3DFYYzhSsCtTFwj/IhIog9DFOxNEqehADd8=; b=pkv3LXFvsOXLgHO+rIKerHKfzTfXOGQphCb2BJxQTsLUZVkRDThiuN7RB8nIC4/0lD Gf4Tldilh2mvri1N+hW6zn/3D0YS/u5SHByxo1RrXbpSFSuL0O+9nCoI5lAQXqidADGJ HJUbZoGYt+Nm1hZsaj/tXX5FbdZF1fV1dORgUpKZMtx0Fj7/YmkaP3hzZ+VW1SaB15B5 rMK957SbnHxwa4gTJg+LmQCrsMKr4ul6cePXQdhgNPqZyjPZW/uA4iPO7xRBQHXExhgu tLneO6m5HTsmMiyF8npw5hqnykImn9arsyG0VMJqJOyi+WQ2f1Ms6xuvEf4fH0S/QYqH mLsg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:from:date:message-id:subject:to; bh=LpAgbHbn3DFYYzhSsCtTFwj/IhIog9DFOxNEqehADd8=; b=pyxU5ll5RMo2Te/vP1XNE9L10mXt/qxjcycTB/D2CO7y/HQz4YyN48vw4AvWC0tFNs d2mra52lsONbkGIZVyXvQbijoz+30JtZHYc8RtQMnTmT6yq4saXLKGP9G8E2DNlNoS0n OIul380LeUtu/Slrt8oOpxvrB0x8Z5mDQmZiuuWaoGmp/e9w6VWMeFUGNYCjjjsC3HSs hFnVO4IIvDEUDm+oN9Rzp46nwo4K7JsQ6q1VhZaftqbeB8GMVcomBMITET+fjI/TgG2O up+RfgAogkuFcvXL1kZsQ/XH289uyigsA65zSio3RWOd5zqgVhr25qSqtadJnD/bRxNv oq+w== X-Gm-Message-State: AMke39k6XS7ho+D2dvldAYRzMy7xbQFg9AlHCCyKFOwb9XNcPVEe8aFORh2wldAxa4qKpBjX5CCzFQdoNoA/NA== X-Received: by 10.202.51.10 with SMTP id z10mr4911131oiz.214.1489006064557; Wed, 08 Mar 2017 12:47:44 -0800 (PST) Original-Received: by 10.202.194.196 with HTTP; Wed, 8 Mar 2017 12:47:43 -0800 (PST) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2607:f8b0:4003:c06::22a X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:212847 Archived-At: --001a113cdfe88c0205054a3e3d26 Content-Type: text/plain; charset=UTF-8 I suggest the following short improvement to documentation of generator functions. It took me very long to understand what's wrong with my code. Problem can be illustrated with this: (require 'generator) (defvar xxx 0) (iter-defun my-iter () (print "A") (let ((xxx nil)) (print "B") (iter-yield 0) (print "C")) (print "D")) (iter-do (x (my-iter)) (print x)) If you evaluate the last form, you'll see "B" and "C" printed twice because `let' for dynamic variable is internally implemented with something similar to `unwind-protect'. However, when documentation doesn't mention it, that's very hard to pinpoint. Paul --001a113cdfe88c0205054a3e3d26 Content-Type: text/plain; charset=US-ASCII; name="generator-doc.diff" Content-Disposition: attachment; filename="generator-doc.diff" Content-Transfer-Encoding: base64 X-Attachment-Id: f_j01frdve0 ZGlmZiAtLWdpdCBhL2RvYy9saXNwcmVmL2NvbnRyb2wudGV4aSBiL2RvYy9saXNwcmVmL2NvbnRy b2wudGV4aQppbmRleCA0MDFhOTk5Y2YyLi5lMjc5YmU4NTU3IDEwMDY0NAotLS0gYS9kb2MvbGlz cHJlZi9jb250cm9sLnRleGkKKysrIGIvZG9jL2xpc3ByZWYvY29udHJvbC50ZXhpCkBAIC03MzAs NyArNzMwLDggQEAgcmVzdWx0IGFzIGl0cyBjb25kaXRpb24gZGF0YS4KIAogQW55IGtpbmQgb2Yg TGlzcCBjb2RlIGlzIHZhbGlkIGluc2lkZSBAdmFye2JvZHl9LCBidXQKIEBjb2Rle2l0ZXIteWll bGR9IGFuZCBAY29kZXtpdGVyLXlpZWxkLWZyb219IGNhbm5vdCBhcHBlYXIgaW5zaWRlCi1AY29k ZXt1bndpbmQtcHJvdGVjdH0gZm9ybXMuCitAY29kZXt1bndpbmQtcHJvdGVjdH0gZm9ybXMgb3Ig YW55IGR5bmFtaWMgQGNvZGV7bGV0fSBiaW5kaW5ncywKK2kuZS4gYmluZGluZ3MgZm9yIHZhcmlh YmxlcyBkZWZpbmVkIHdpdGggQGNvZGV7ZGVmdmFyfS4KIAogQGVuZCBkZWZtYWMKIAo= --001a113cdfe88c0205054a3e3d26--