From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: Opaque objects and Emacs documentation Date: Wed, 22 Jul 2020 19:37:16 +0300 Message-ID: References: <20200712184908.13140.5739@vcs0.savannah.gnu.org> <20200712184909.BBC61209B1@vcs0.savannah.gnu.org> <7bf4d6ef-c0ec-43dc-ad5d-f6e81422ad90@yandex.ru> <83zh84m5ws.fsf@gnu.org> <3dd1c224-69b2-40af-5b2e-43a310253632@yandex.ru> <83tuybmtxs.fsf@gnu.org> <859f594b-1343-6d26-e1ac-7157c44eb56c@yandex.ru> <83a6zyk4tt.fsf@gnu.org> <6edffb7d-7708-534f-93ad-bf9180f5e0ed@yandex.ru> <835zamjsvk.fsf@gnu.org> <831rlajock.fsf@gnu.org> <1fcdc463-b3ab-2d32-31d7-904783ae0d81@yandex.ru> <83y2nii6sk.fsf@gnu.org> <69716ecb-8984-23e0-8b44-322ea3582384@yandex.ru> <837duxgcmw.fsf@gnu.org> <83wo2wfytr.fsf@gnu.org> <70c95ed1-cf68-32c6-49a9-6ed67f20b4c9@yandex.ru> <83imeffwth.fsf@gnu.org> <1d2e5168-d69a-147a-8905-61af2d0b4379@yandex.ru> <83d04nfr5q.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="39038"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 Cc: rms@gnu.org, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Jul 22 18:37:58 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jyHkj-000A3O-JR for ged-emacs-devel@m.gmane-mx.org; Wed, 22 Jul 2020 18:37:57 +0200 Original-Received: from localhost ([::1]:49658 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jyHki-00027q-KB for ged-emacs-devel@m.gmane-mx.org; Wed, 22 Jul 2020 12:37:56 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41234) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jyHkB-0001gg-AV for emacs-devel@gnu.org; Wed, 22 Jul 2020 12:37:23 -0400 Original-Received: from mail-ej1-x632.google.com ([2a00:1450:4864:20::632]:43030) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jyHk9-0008Jc-GQ; Wed, 22 Jul 2020 12:37:23 -0400 Original-Received: by mail-ej1-x632.google.com with SMTP id a21so2883785ejj.10; Wed, 22 Jul 2020 09:37:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=dRHvbdqWGNEtIfv7kZ4oqGe4H+Beu5bfIaLXbbGI8Mk=; b=oh44N/pd/iESeSLoqiXFCQ/IzxX3Vw3/B+j51HKHobYj+nZxDa9Tre+0VqqjV1ZjrM pkMPLx/5Xxsb+Xe2fv+ZrnO14HEgMJzj/VU/Kh5TQOHMEQLNqNc9VYIgoFqEyDfozC8e GWGhFkM2fCeZVeBx+5W9gIQ6wHje9CrE4S5Ai8F3SY20T7jPe1fAq6VYqxHQZonvWaop MQls+YCt83nzftnsx+kLjXOEPeIHbGniSP1V3Y0OOdCvebGYjYEcAAEHnt4KqkfLFcKk VYVghWthPNPKkHZgT5Bzz+NR8s9XIgwdi8HI601I0DeTMYS0UwCL/kMJpI8QrTFOjdeU cYog== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=dRHvbdqWGNEtIfv7kZ4oqGe4H+Beu5bfIaLXbbGI8Mk=; b=KPJKawPDNy62sjjeW9oU6j68xFJCviNYX7CsZ2re8ILCX9DG+pKUYIOMiBRTsU96T9 KcMwuYI06ivB1iuGUPwrRzETe+hsBWvgSRAqAF2jqKwPkx7Kyzdx9Vkh91NqfIAcDPZb aKDy08xVVAF+2eFe8Qki4ScLXHPbHuVfl5exyoDzCugEt/H6qdZPUh8S0kSfYaMkWsr/ D44UzoPzQ2j8JwGlBU081izE+rxoRs5sJI9u7mMRMME2a4xIdJq+3iY3Ky1R17sfo0xP AHBk8BPyZwlfiO+GZafgLjmTfQAx7lI1xc1EOfOmj7ke8LR5RzSIRzR+DwltmnxBVwXR 5QEw== X-Gm-Message-State: AOAM530Z9Rfjqpu9Ke9RYdvv/5/71iF1sfSJOONM69a4hn+/i2p3Bxs9 1oSEbHxZ4u0dublM3u88sxFH96ZO X-Google-Smtp-Source: ABdhPJxuQKkWx2heTjLWD4vpe3IiyD2yV2B8DzHApRLbMEK/UpUUPga0qkzBKoR1JuF/PD8B0ccevw== X-Received: by 2002:a17:906:19c9:: with SMTP id h9mr377260ejd.526.1595435838682; Wed, 22 Jul 2020 09:37:18 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id q21sm109295ejr.75.2020.07.22.09.37.17 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 22 Jul 2020 09:37:18 -0700 (PDT) In-Reply-To: <83d04nfr5q.fsf@gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::632; envelope-from=raaahh@gmail.com; helo=mail-ej1-x632.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: 0 X-Spam_score: 0.0 X-Spam_bar: / X-Spam_report: (0.0 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=1, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:253165 Archived-At: On 22.07.2020 19:30, Eli Zaretskii wrote: >> If I drop both instances of the word "general" from the sentence I >> quoted, there will be nothing left. > > In _my_ sentence above there's only one "general". the other one is > "generics", a different word. Same root, similar purpose. Describing what generics return is fine, the project-current's docstring already does that, actually. The issue is in the manner of the description. You insist on describing the data structure (as opposed to describing associated behaviors), but the callers of that function should never need it. >>>> And speaking of "transient", it's not helpful to say it returns a cons >>>> (transient . root) because that doesn't say anything about the project >>>> behavior anyway (which is the important part). >>> >>> A backend that receives such an object will need to be prepared for >>> it. >> >> The backend returned that value, so it is surely prepared. > > No, it's project-current that did. project-current received it from the backend and returned it to the caller.