From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2 Date: Thu, 15 Jul 2021 18:57:46 +0300 Message-ID: <83sg0f603p.fsf@gnu.org> References: <8735shrl57.fsf@tullinup.koldfront.dk> <83v95c7v3v.fsf@gnu.org> <87bl74evd7.fsf@gnus.org> <87bl74ry2z.fsf@gnus.org> <831r7z7jgl.fsf@gnu.org> <87r1fzinu1.fsf@gnus.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="5078"; mail-complaints-to="usenet@ciao.gmane.io" Cc: asjo@koldfront.dk, stefan@marxist.se, monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Lars Ingebrigtsen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Jul 15 17:59:05 2021 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 1m43lQ-00014w-9y for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Jul 2021 17:59:04 +0200 Original-Received: from localhost ([::1]:53800 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m43lO-0001Ed-VS for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Jul 2021 11:59:02 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43990) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m43kQ-0007gQ-JO for emacs-devel@gnu.org; Thu, 15 Jul 2021 11:58:03 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:53894) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m43kP-0006SH-OS; Thu, 15 Jul 2021 11:58:01 -0400 Original-Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:2654 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m43kP-0002oS-CJ; Thu, 15 Jul 2021 11:58:01 -0400 In-Reply-To: <87r1fzinu1.fsf@gnus.org> (message from Lars Ingebrigtsen on Thu, 15 Jul 2021 17:44:22 +0200) 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:271261 Archived-At: > From: Lars Ingebrigtsen > Date: Thu, 15 Jul 2021 17:44:22 +0200 > Cc: Eli Zaretskii , Stefan Kangas , > asjo@koldfront.dk, emacs-devel@gnu.org > > Stefan Monnier writes: > > >> IMO, examples are for the manual, not for the doc strings. If some > >> parts of our manuals could benefit from more examples, patches for > >> that would be welcome. > > I think having some examples is fine in doc strings -- it can be > difficult to explain some concepts in words, but a simple example can be > a really efficient way to say what a function does. > > But we should indeed not go overboard with examples in doc strings -- > that's better left for the manual. The danger of going overboard is exactly what bothers me. Which is why I think examples in doc strings should be used in exceptional cases, where they are absolutely necessary. Not as a "why not?" addition.