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: master 1e3b0f2: Improve doc strings of project.el Date: Mon, 13 Jul 2020 21:26:23 +0300 Message-ID: <87d5e4ff-e12b-85bb-e333-abc4e32cfdb3@yandex.ru> References: <87bllfqj82.fsf@warpmail.net> <83imf2t4w4.fsf@gnu.org> <95fd893e-0da5-4cdc-a3e8-3c22af750aae@yandex.ru> <837dvfs6wg.fsf@gnu.org> <8bc1f381-248f-5cee-c3c6-a29d411a2f74@yandex.ru> <837dvbphs0.fsf@gnu.org> <83365zp78d.fsf@gnu.org> <831rlipmgg.fsf@gnu.org> <83lfjqnsa6.fsf@gnu.org> <294212ed-5a6e-0a7f-e1c2-97e917f1e6e1@yandex.ru> <83eepgomts.fsf@gnu.org> <83a704okmg.fsf@gnu.org> <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> <837dv8oida.fsf@gnu.org> <834kqcoghk.fsf@gnu.org> <99bb8976-580a-ef8e-6b7d-130c3ca5cb8a@yandex.ru> <83y2nom3hy.fsf@gnu.org> <455BA940-0BFF-4229-A60D-D33A2FF3385B@gnu.org> <9414A931-C678-4741-8B77-4F9FD2ECC339@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="37242"; 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 To: Eli Zaretskii , Gregory Heytings , "Gregory Heytings via Emacs development discussions." Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jul 13 20:27:14 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 1jv3AX-0009ak-Vp for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 20:27:13 +0200 Original-Received: from localhost ([::1]:38706 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jv3AW-0008PC-SI for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 14:27:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38316) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jv39q-0007zT-Sd for emacs-devel@gnu.org; Mon, 13 Jul 2020 14:26:30 -0400 Original-Received: from mail-wm1-x336.google.com ([2a00:1450:4864:20::336]:40760) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jv39o-0003bM-NO; Mon, 13 Jul 2020 14:26:30 -0400 Original-Received: by mail-wm1-x336.google.com with SMTP id f139so608530wmf.5; Mon, 13 Jul 2020 11:26:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=rjK5GnZFuqpqH02BrOhT/p9CiG6jKn/p4MUhpR1wfns=; b=vPzpEfsHVsJ3k2yr1QMz2Vu8w1/TBnE/YgYF4HkGFY/Tm95EWpP79TJGzsEhp/yNB+ z48gyk+BiJD0G9arceAhzLstvgC+7r1JaJHtl4BvSuwts76shWtJSXbwOWXZCG2zVmXe fD9MXCOGMpNbZA4QTGhgj36YSZ9dLEZYGbqfQt3ynetYDI46WPP09l0uMK8n6oUMmdPW SFiPQL3NwD86ofc9tZb8UhJ0w3cYwza1kts2HWGtLBPpLyoaugngp4G12KuQS0TvJNGP jetoUFfq30QxQSDHBx4ia53PvVGailgsdpBtP++cbs39wsTL+m48SwY7WRt5C2ooGIvD ChsQ== 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:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=rjK5GnZFuqpqH02BrOhT/p9CiG6jKn/p4MUhpR1wfns=; b=f3TGUJLptYh94fIoBJOpeKCJCdApYU19MpqaFSFQwrDYli4EBFSIXEqpsGxCluqfaf +BMfBpG1wXA9dBzHBz88zXvKyW8lXDYAcZzExFNn9QmXk18W/sss4NWiFBmijj53KwxD y3u7NhLAAlNIuYHI6MJk2nuOeZQaQb48eQJiSwJWHZbm5H75ULF/EesFYCrBN0v/eavY 8x5kjylY0vn0ktClZc9jpnSUDntlghHF9WNqglusvsGXOTvemAGWgUJ7q4tp4f62zR9d nh4iLutq0Zf6/GGBMWYqB/PebByW/4cACR0VZkeJ9cPmDcIAc2Tov7t/h+Hoj6JJHhow uSVw== X-Gm-Message-State: AOAM530tysWKQdGaoCn2HRWktAbvR3H0PUAHBPsGDKo2GWMWSzBJNU1E xVWgupPP7AeYjmMmmP2RU1GkF/G/ X-Google-Smtp-Source: ABdhPJwEjztwgWlyuvQXE/Oo1RLLbKSQ/ayroTKnCTL/cFsYf5WXRPtIDbtYSLxEAdBqLWlgOFcZQg== X-Received: by 2002:a1c:2d91:: with SMTP id t139mr678655wmt.3.1594664786643; Mon, 13 Jul 2020 11:26:26 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id 68sm556524wmz.40.2020.07.13.11.26.24 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 13 Jul 2020 11:26:25 -0700 (PDT) In-Reply-To: <9414A931-C678-4741-8B77-4F9FD2ECC339@gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::336; envelope-from=raaahh@gmail.com; helo=mail-wm1-x336.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:252920 Archived-At: On 13.07.2020 11:53, Eli Zaretskii wrote: >> I might be wrong, but in that case I think Dmitry's viewpoint is that >> this >> information should not be placed in the doc strings, but in the >> comments >> in the source file. > Maybe so, but the suggestion to move what I added to the doc strings into comments was never voiced by Dmitry until the very last message, and even there he is still firmly against documenting the form of the return value, no matter where. One the contrary, I did say that this kind of information is better suited for comments, if we must have it. For example, you can add it to project-try-vc somewhere. To me it seems gratuitous/too obvious from the implementation already, but I don't object to it on principle.