From patchwork Sat Jan 6 23:01:43 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tobin Harding X-Patchwork-Id: 10148077 X-Patchwork-Delegate: herbert@gondor.apana.org.au Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 21A2B60134 for ; Sat, 6 Jan 2018 23:01:56 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 06419223C6 for ; Sat, 6 Jan 2018 23:01:56 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id ECEF226E54; Sat, 6 Jan 2018 23:01:55 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 341C7223C6 for ; Sat, 6 Jan 2018 23:01:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752470AbeAFXBy (ORCPT ); Sat, 6 Jan 2018 18:01:54 -0500 Received: from out3-smtp.messagingengine.com ([66.111.4.27]:53859 "EHLO out3-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752249AbeAFXBx (ORCPT ); Sat, 6 Jan 2018 18:01:53 -0500 Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailout.nyi.internal (Postfix) with ESMTP id C08F920D16; Sat, 6 Jan 2018 18:01:52 -0500 (EST) Received: from frontend2 ([10.202.2.161]) by compute5.internal (MEProxy); Sat, 06 Jan 2018 18:01:52 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tobin.cc; h=cc :date:from:message-id:subject:to:x-me-sender:x-me-sender :x-sasl-enc; s=fm2; bh=3E4cSpHIJSFNBbOPcy1ztE/F4/U55Yj8eXyXCZdYE iY=; b=Cxd4W36WohEZnq70l2cj8fxT74k8dzccNYbDZ4vJ5Op5nl+TZMRxGvGoa stWsNL11cyyc22IvrP/p31NOe6MA1XywNi07QoNYre1bKpS4SceMjHuJ1/WRtwCw TCmTN25P/Vd5ko6l4/8OMgoct+P32BYK2yuQLmnoLBKk/gfnf+nTVzb53rp4l6Eq pSa9vAVUqDBVqNBz07EQ93m8mjcmJQpmvZ8WW3kioWgzN77b5N9JI8TgwfZ5FNFV HVUSjCySURM9XJT+vlilx+6f1401jCOIpUfJdRnVF187I8QkYrnPEZ6zsCw/D0or zHpryHg2l7NzydXoecClqZphVlekg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:date:from:message-id:subject:to :x-me-sender:x-me-sender:x-sasl-enc; s=fm1; bh=3E4cSpHIJSFNBbOPc y1ztE/F4/U55Yj8eXyXCZdYEiY=; b=AOSSV3VSRJhvd6s0pwv22XtBlYXUIw5CE XZC/ewQJSMlwGEWskqkTKSJdrsgxFtKrF5ujvo+sfCS0IwrcoZrJe11/pufJbO7T NhzYaXJs1tCgtSviKozn7pta1t8XrjRE0835gBIpULPsZdFGsVd2paNSkgd/64ay feWZUebZBczSxJOmtYi937KT0D/whinlLEmBLT9TN04Vv9BB042NQP5HaAKaInHu dXbmAXCbPyyi3Q8gJpzs6ye5PPFWoOl/B8JdukOBtDJX+640kfbxjVd3jeZUlwDk 4uS8GH6jwOLSB6/vzPmgv7t094Ca138PiHfKt6B9ti3N62qSZcEBw== X-ME-Sender: Received: from localhost (106-69-197-55.dyn.iinet.net.au [106.69.197.55]) by mail.messagingengine.com (Postfix) with ESMTPA id 14371246D0; Sat, 6 Jan 2018 18:01:51 -0500 (EST) From: "Tobin C. Harding" To: Herbert Xu , "David S. Miller" Cc: "Tobin C. Harding" , linux-crypto@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH] crypto: clear htmldocs build warnings for crypto/hash Date: Sun, 7 Jan 2018 10:01:43 +1100 Message-Id: <1515279703-14070-1-git-send-email-me@tobin.cc> X-Mailer: git-send-email 2.7.4 Sender: linux-crypto-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP SPHINX build emits multiple warnings of kind: warning: duplicate section name 'Note' (when building kernel via make target 'htmldocs') This is caused by repeated use of comments of form: * Note: soau soaeusoa uoe We can change the format without loss of clarity and clear the build warnings. Add '**[mandatory]**' or '**[optional]**' as kernel-doc field element description prefix This renders in HTML as (prefixes in bold) final [mandatory] Retrieve result from the driver. This function finalizes the transformation and retrieves the resulting hash from the driver and pushes it back to upper layers. No data processing happens at this point unless hardware requires it to finish the transformation (then the data buffered by the device driver is processed). Signed-off-by: Tobin C. Harding --- This patch begs the question why the other members of struct ahash_alg are not marked? Some are marked 'optional' some 'mandatory'. It would seem that if the marking were necessary for some members it is necessary for all to eliminate ambiguity? thanks include/crypto/hash.h | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/include/crypto/hash.h b/include/crypto/hash.h index 0ed31fd80242..d1cd75faff40 100644 --- a/include/crypto/hash.h +++ b/include/crypto/hash.h @@ -71,12 +71,11 @@ struct ahash_request { /** * struct ahash_alg - asynchronous message digest definition - * @init: Initialize the transformation context. Intended only to initialize the + * @init: **[mandatory]** Initialize the transformation context. Intended only to initialize the * state of the HASH transformation at the beginning. This shall fill in * the internal structures used during the entire duration of the whole * transformation. No data processing happens at this point. - * Note: mandatory. - * @update: Push a chunk of data into the driver for transformation. This + * @update: **[mandatory]** Push a chunk of data into the driver for transformation. This * function actually pushes blocks of data from upper layers into the * driver, which then passes those to the hardware as seen fit. This * function must not finalize the HASH transformation by calculating the @@ -85,20 +84,17 @@ struct ahash_request { * context, as this function may be called in parallel with the same * transformation object. Data processing can happen synchronously * [SHASH] or asynchronously [AHASH] at this point. - * Note: mandatory. - * @final: Retrieve result from the driver. This function finalizes the + * @final: **[mandatory]** Retrieve result from the driver. This function finalizes the * transformation and retrieves the resulting hash from the driver and * pushes it back to upper layers. No data processing happens at this * point unless hardware requires it to finish the transformation * (then the data buffered by the device driver is processed). - * Note: mandatory. - * @finup: Combination of @update and @final. This function is effectively a + * @finup: **[optional]** Combination of @update and @final. This function is effectively a * combination of @update and @final calls issued in sequence. As some * hardware cannot do @update and @final separately, this callback was * added to allow such hardware to be used at least by IPsec. Data * processing can happen synchronously [SHASH] or asynchronously [AHASH] * at this point. - * Note: optional. * @digest: Combination of @init and @update and @final. This function * effectively behaves as the entire chain of operations, @init, * @update and @final issued in sequence. Just like @finup, this was