From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 84BC16DE12F3 for ; Sun, 20 Aug 2017 12:31:00 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" X-Spam-Flag: NO X-Spam-Score: 0.034 X-Spam-Level: X-Spam-Status: No, score=0.034 tagged_above=-999 required=5 tests=[AWL=0.054, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01] autolearn=disabled Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id uMa05XKDgUAW for ; Sun, 20 Aug 2017 12:30:59 -0700 (PDT) Received: from mail-lf0-f65.google.com (mail-lf0-f65.google.com [209.85.215.65]) by arlo.cworth.org (Postfix) with ESMTPS id 2AFE96DE12DC for ; Sun, 20 Aug 2017 12:30:51 -0700 (PDT) Received: by mail-lf0-f65.google.com with SMTP id f7so4337554lfg.0 for ; Sun, 20 Aug 2017 12:30:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nikula-org.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :in-reply-to:references; bh=DvTHbah40tQhoWD1FQZgyedurfO8EDfzDD7ThIc/tN4=; b=Vpl1GgFBAHRYxRLrUUMJw+OpDCz1Gg954ZDJj7rEL8R165jbouRru35rfA4i2LpG9y rRtcNwqthSQt4DRiLN9re2XkAq3+W3DXVAZELxdTJA7CGnqI5rrqQefxca6WXtbobHe7 sF8wiiMWirHzBEyCSPlEUX4qk7I1FrhTLNBH4IJD36J5jCnU8JOO2c8DlJpIai171XF2 /+hKzbzYX5xAhoJCEP3ZSdZHm9glsctzE6SP4bgRknh5O4ZcdqBZgz23MMApm+AYssZ8 c6/La9hqG50bIliCJ9wdS5tQEK9KLe3X+YKbt1yD2rXcZ+BtPCqQtp4Z249exwCAoZaI 5Rvw== 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:date:message-id:in-reply-to :references:in-reply-to:references; bh=DvTHbah40tQhoWD1FQZgyedurfO8EDfzDD7ThIc/tN4=; b=p1cd8jM6nM4sGyrymqpAEPMyU8nGcWM1UO7LHxn4W/FVywiWCX+5qqHZSwGM9lE0kr eaJU7Cnf9ZdVK9b0USpvCzrB0OlSQHYB+KwRKU8r0aihBlq/2iORrAr9s72CYyVt8QxD 5sAL3jcZKZqx1F0a1VNqDxxdSioQf/rb500FMC9AEt+Y0G1JhukJFyKShofQOzp8IGUA WWQ9mr/H8arbp+VKQm4JZorYvzrcdb7PjJJFWzY32kqhoU0Ddfc/joUGev6OVUE38bVe tRjgnMRHd/6kt4nRdRBq1tibfLKH9mE6drw580Xoo76Q464W5AT4gbafQKir4Tw2tfP+ hi2Q== X-Gm-Message-State: AHYfb5j+7E2D3ZVl+2mbAMVLiP/m3NrUfgy9HLPGCgZZQiVECsC8AyLh jhdLk+SVdAH2xqQkTRkFgA== X-Received: by 10.25.19.24 with SMTP id j24mr607259lfi.193.1503257449064; Sun, 20 Aug 2017 12:30:49 -0700 (PDT) Received: from localhost (mobile-access-5d6aa6-119.dhcp.inet.fi. [93.106.166.119]) by smtp.gmail.com with ESMTPSA id 2sm2066943ljo.10.2017.08.20.12.30.47 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 20 Aug 2017 12:30:48 -0700 (PDT) From: Jani Nikula To: notmuch@notmuchmail.org Subject: [RFC PATCH 4/4] lib: add reStructuredText bling for API documentation in notmuch.h Date: Sun, 20 Aug 2017 22:30:39 +0300 Message-Id: X-Mailer: git-send-email 2.11.0 In-Reply-To: References: In-Reply-To: References: X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 20 Aug 2017 19:31:00 -0000 Document notmuch_database_create() using as much bling as possible. This is pretty nice in the output, but probably too excessive in source code. Nonetheless, it's an example of what could be done. --- lib/notmuch.h | 45 +++++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/lib/notmuch.h b/lib/notmuch.h index ab01944cb2b0..c3307d5835dd 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -229,38 +229,43 @@ typedef struct _notmuch_param notmuch_param_t; #endif /* __DOXYGEN__ */ /** - * Create a new, empty notmuch database located at 'path'. + * Create a new, empty notmuch database located at ``path``. * - * The path should be a top-level directory to a collection of - * plain-text email messages (one message per file). This call will - * create a new ".notmuch" directory within 'path' where notmuch will - * store its data. + * This call will create a new ``.notmuch`` directory within ``path`` + * where notmuch will store its data. * - * After a successful call to notmuch_database_create, the returned - * database will be open so the caller should call - * notmuch_database_destroy when finished with it. + * After a successful call to :c:func:`notmuch_database_create()`, the + * returned database will be open so the caller should call + * :c:func:`notmuch_database_destroy()` when finished with it. * * The database will not yet have any data in it - * (notmuch_database_create itself is a very cheap function). Messages - * contained within 'path' can be added to the database by calling - * notmuch_database_add_message. + * (:c:func:`notmuch_database_create()` itself is a very cheap + * function). Messages contained within ``path`` can be added to the + * database by calling :c:func:`notmuch_database_add_message()`. * * In case of any failure, this function returns an error status and - * sets *database to NULL (after printing an error message on stderr). + * sets ``*database`` to ``NULL`` (after printing an error message on + * ``stderr``). * - * Return value: + * @param path The ``path`` should be a top-level directory to a + * collection of plain-text email messages (one message per file). * - * NOTMUCH_STATUS_SUCCESS: Successfully created the database. + * @param database Pointer to database. * - * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL. + * @return + * :c:macro:`NOTMUCH_STATUS_SUCCESS`: Successfully created the database. * - * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * :c:macro:`NOTMUCH_STATUS_NULL_POINTER`: The given ``path`` + * argument is ``NULL``. * - * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to create the - * database file (such as permission denied, or file not found, - * etc.), or the database already exists. + * :c:macro:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of memory. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * :c:macro:`NOTMUCH_STATUS_FILE_ERROR`: An error occurred trying to + * create the database file (such as permission denied, or file not + * found, etc.), or the database already exists. + * + * :c:macro:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian exception + * occurred. */ notmuch_status_t notmuch_database_create (const char *path, notmuch_database_t **database); -- 2.11.0