From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: jamil egdemir Newsgroups: gmane.lisp.guile.user Subject: Re: docstrings in the reference manual Date: Tue, 16 Dec 2014 05:54:28 -0500 Message-ID: References: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: ger.gmane.org 1418727286 19377 80.91.229.3 (16 Dec 2014 10:54:46 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 16 Dec 2014 10:54:46 +0000 (UTC) To: guile-user Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Tue Dec 16 11:54:41 2014 Return-path: Envelope-to: guile-user@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Y0pm3-0000kd-Ke for guile-user@m.gmane.org; Tue, 16 Dec 2014 11:54:39 +0100 Original-Received: from localhost ([::1]:43975 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0pm3-0008UN-9p for guile-user@m.gmane.org; Tue, 16 Dec 2014 05:54:39 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52819) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0plu-0008Tp-Fb for guile-user@gnu.org; Tue, 16 Dec 2014 05:54:31 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Y0plt-0005cM-9b for guile-user@gnu.org; Tue, 16 Dec 2014 05:54:30 -0500 Original-Received: from mail-wg0-x230.google.com ([2a00:1450:400c:c00::230]:49754) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0plt-0005cI-2G for guile-user@gnu.org; Tue, 16 Dec 2014 05:54:29 -0500 Original-Received: by mail-wg0-f48.google.com with SMTP id y19so16933292wgg.21 for ; Tue, 16 Dec 2014 02:54:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; bh=scZVG0w7lu9wukUK/DyLer94RAY/8Y/LLWDNsRiWXbA=; b=B7JJkphxvIGnGRAciNYehtoW6Anxhtrf7iKExmadcHqnLGqMMF0UxkyVlT8o7Kj35p iXl42RNYVowMEef5mvtXDRYQ+J9Wk0NokNtwgdDRD02uyS/4fSmSddRJATUq6eAcuNDE a3+8ctDy/P0jdo/fGlluwEzrd9qic+p5Hyt0FgjCrTGOT/Ol9AhbpGzKAQ7gvOtavFWy lYl6RLRYlmWMT2Il6TMHEHobuhZa3dkIVbO7ECGCr2tX8LwjhPzN3ekXyRfjn2n0JeZm wF/s12A3unmT4hukXihU9MXOobIDAXeWLr3eZyAhDlVhkNurb138wXGAnWtpNZ01aDWI TSdA== X-Received: by 10.180.205.177 with SMTP id lh17mr3524398wic.75.1418727268096; Tue, 16 Dec 2014 02:54:28 -0800 (PST) Original-Received: by 10.27.6.202 with HTTP; Tue, 16 Dec 2014 02:54:28 -0800 (PST) In-Reply-To: X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:400c:c00::230 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Original-Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.user:11674 Archived-At: Panicz, On 12/16/14, Panicz Maciej Godek wrote: > It is described here: > https://www.gnu.org/software/guile/manual/html_node/Procedure-Properties.html > (the "procedure-documentation" entry): > > Return the documentation string associated with `proc'. By > convention, if a procedure contains more than one expression and > the first expression is a string constant, that string is assumed > to contain documentation for that procedure. Good eyes! > I agree though that it can be difficult to find, and it would be a bit > better if it used the word "docstring" (like "that string is assumed to > contain documentation for that procedure (so-called 'docstring')"), to make > it easier to find, and that there should be a "docstring" index entry as > well. I agree. This info on docstrings is tucked away pretty well. I noticed here in the ref man: https://www.gnu.org/software/guile/manual/html_node/Reporting-Bugs.html#Reporting-Bugs that documentation that is unclear is considered a bug (last bullet in the first list). If you think it makes sense then I'll submit a bug on the documentation with this info and your suggestion. -j -- ------------------------------------------------------------- Jamil Egdemir unclejamil@gmail.com http://www.power-quant.com -------------------------------------------------------------