From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: =?utf-8?Q?Etienne_Prud=E2=80=99homme?= Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Wed, 07 Jun 2017 22:29:47 -0400 Message-ID: <878tl3rz38.fsf@x230.lts> References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> <7acc7d4f-23cc-4b6a-b062-ef92805e465b@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1496889000 28306 195.159.176.226 (8 Jun 2017 02:30:00 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 8 Jun 2017 02:30:00 +0000 (UTC) User-Agent: Emacs/25.2 (gnu/linux) Cc: Stephen Leake , emacs-devel To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jun 08 04:29: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 1dInCt-00079R-VB for ged-emacs-devel@m.gmane.org; Thu, 08 Jun 2017 04:29:56 +0200 Original-Received: from localhost ([::1]:46987 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dInCz-0008JT-AW for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 22:30:01 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44089) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dInCs-0008JD-IQ for emacs-devel@gnu.org; Wed, 07 Jun 2017 22:29:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dInCp-000509-GT for emacs-devel@gnu.org; Wed, 07 Jun 2017 22:29:54 -0400 Original-Received: from mail-qt0-x244.google.com ([2607:f8b0:400d:c0d::244]:35136) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dInCp-000505-Bk for emacs-devel@gnu.org; Wed, 07 Jun 2017 22:29:51 -0400 Original-Received: by mail-qt0-x244.google.com with SMTP id x58so5373308qtc.2 for ; Wed, 07 Jun 2017 19:29:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=0RmRzQDGQSQTdOAz358cDSJU/+w0+KAFPz68qK+uO+E=; b=L39yNLkzYulTfz+bfAyoH1ziqzOQLQuOSq/A1EKQsnEVPXhxTnRDwpSZqfE70lNXFg 4B5jij6+UEv9tifbJIbXCOKJo1/apgriJJZLBXzwZ2rXVyHP0N82wB3PUmuLkgF2OLMm wMa+ejTXrEcxRNPuO/k1VKtoXAzQpEtqNZH3S/6G3xyBATkSdZA5QOfTRwDP1XMz0JpR rWSAYcMS4LD3yJ4JKQ0GmkfQ674ZGyFpbAWnv8B/sYMkqm6vcQHtIGD6TfoQ5Z4rwoeG Hh/7HjwbUgtznpAnNq44Dmpk0V/JNjHye0ImZk3vOznA41U1VOpH+6YkgqMfYa+4TstN RczA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=0RmRzQDGQSQTdOAz358cDSJU/+w0+KAFPz68qK+uO+E=; b=IiQpCAkkDYTNVesH/BnHZU/BJuniodADnziuvDfT5u7Jwdy+mpf9bfz75feOV/kezW TINs+oiGl+Ux451FKGFezT8l+/IzaconVg/bXK7dsniGb7waRjfHb0R9P0BeIp+DXiZm vdVJ3D9kaGUYzo1BplR4SPRBn3nPVtAYh5/6wW7i0I/VSs1ThgFkkpFNom95DYMvpNNO bT34JDnVOtlkDMX2RNfNsc5igMoUxlHeHlbq0zZHXd/HxNA5ohy/AClomjW7TlD29PUU CkCDDH6K9BCcIcoU0550fJZt24HUXXpNqf4l2MFBPC64S1SRD9YRAkxKuD8aVla2Thm6 cE6A== X-Gm-Message-State: AODbwcBReIjXRyBuYRSKfwk6eELtxa+4ICZ08mg2xlCxDYeeWuDBUWnz hO+XqXCAWev6jA== X-Received: by 10.200.35.129 with SMTP id q1mr43729083qtq.129.1496888989345; Wed, 07 Jun 2017 19:29:49 -0700 (PDT) Original-Received: from localhost (modemcable232.49-20-96.mc.videotron.ca. [96.20.49.232]) by smtp.gmail.com with ESMTPSA id f72sm2253460qka.56.2017.06.07.19.29.48 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 07 Jun 2017 19:29:48 -0700 (PDT) In-Reply-To: <7acc7d4f-23cc-4b6a-b062-ef92805e465b@default> (Drew Adams's message of "Tue, 6 Jun 2017 13:36:33 -0700 (PDT)") X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:400d:c0d::244 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:215514 Archived-At: Drew Adams writes: > And this is not JavaDoc. The Elisp manual is not purely > and simply an API reference manual. It=E2=80=99s worth mentioning that JavaDoc documentation style is particula= rly useful for Object-Oriented Programming and strongly typed languages. I think it=E2=80=99s even mandatory with OOP to be readable. However, I also think Jean-Christophe makes a good point about documentation generation. Not with duplication, but semantic support. While documentation support is awesome in Emacs with GNU libraries, it=E2= =80=99s not always so with third-party documentation tools. I=E2=80=99m thinking a= bout Zeal (and to a very limited extent Dash that is not free). Those tools are highly effective for semantic indexation for newcomers since they offer a simple interface for hundred FLOSS libraries. GNU projects are almost nonexistent. I=E2=80=99ve been trying in the past to port GNU projects documentation and= I finally gave up. I find Texinfo to be very limited when it comes to semantic support. It=E2=80=99s really hard to extract meaningful definitio= ns from texi files.