From patchwork Wed Dec 17 20:12:04 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 42396 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-ee0-f70.google.com (mail-ee0-f70.google.com [74.125.83.70]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 1EE5526C8B for ; Wed, 17 Dec 2014 20:12:31 +0000 (UTC) Received: by mail-ee0-f70.google.com with SMTP id b57sf13163eek.9 for ; Wed, 17 Dec 2014 12:12:30 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:from:to:date:message-id:subject :precedence:list-id:list-unsubscribe:list-archive:list-post :list-help:list-subscribe:mime-version:content-type :content-transfer-encoding:errors-to:sender:x-original-sender :x-original-authentication-results:mailing-list; bh=XnYFfe0ZrzS6Jg5aUloJWTTjEk23g9AMDoaxCbSfqjA=; b=RDk7KFavqXadHikMjZYUtefNI7pPeUFIW4+jrqqO6mGtrRGAKlDM8h0GLJP90n5dq4 K78uwgrpDTBbsQyBkN8aHgB7CA92mbR8NBKbAMkLf0HMl159tTsHmGEBtIq8OYSeA0k8 E4AUhgs89/Fgt0TPcanA1Qjw7KJOmkydz346EYV05XXOdDnvlE0Bzds/d/StL4wuXKNT r5tqddsq/tiLqwpFGcOxs/thSjpxgcd8Vu1fpTeloAZlh/gBa+p6XjCJWxV9BCQodJTY 0H/ErUBP8uGVMN9qCBJ8Ae5k2r/G+X/Ph38VQmfdgOklPjZiNtoGGV/PEgc8mmqB9vYh ajXw== X-Gm-Message-State: ALoCoQlmC+CfPNkKX6ZZWg6HHSLNdvGWATAUzyryzZhsgKb7WlZGShqF2LzgAhzKsR5VLqpvIw7S X-Received: by 10.112.146.104 with SMTP id tb8mr3654lbb.22.1418847150054; Wed, 17 Dec 2014 12:12:30 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.36.70 with SMTP id o6ls764327laj.28.gmail; Wed, 17 Dec 2014 12:12:29 -0800 (PST) X-Received: by 10.112.159.129 with SMTP id xc1mr43061488lbb.24.1418847149803; Wed, 17 Dec 2014 12:12:29 -0800 (PST) Received: from mail-la0-f44.google.com (mail-la0-f44.google.com. [209.85.215.44]) by mx.google.com with ESMTPS id ga1si4810494lbc.122.2014.12.17.12.12.29 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 17 Dec 2014 12:12:29 -0800 (PST) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.44 as permitted sender) client-ip=209.85.215.44; Received: by mail-la0-f44.google.com with SMTP id gd6so13972997lab.17 for ; Wed, 17 Dec 2014 12:12:29 -0800 (PST) X-Received: by 10.112.135.229 with SMTP id pv5mr42982304lbb.52.1418847149322; Wed, 17 Dec 2014 12:12:29 -0800 (PST) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.142.69 with SMTP id ru5csp1477013lbb; Wed, 17 Dec 2014 12:12:28 -0800 (PST) X-Received: by 10.224.54.203 with SMTP id r11mr17330814qag.62.1418847147536; Wed, 17 Dec 2014 12:12:27 -0800 (PST) Received: from ip-10-35-177-41.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id f6si5855019qgf.13.2014.12.17.12.12.25 (version=TLSv1 cipher=RC4-SHA bits=128/128); Wed, 17 Dec 2014 12:12:27 -0800 (PST) Received-SPF: none (google.com: lng-odp-bounces@lists.linaro.org does not designate permitted sender hosts) client-ip=54.225.227.206; Received: from localhost ([127.0.0.1] helo=ip-10-35-177-41.ec2.internal) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1Y1KxL-0008Nz-J7; Wed, 17 Dec 2014 20:12:23 +0000 Received: from mail-qa0-f47.google.com ([209.85.216.47]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1Y1KxF-0008LL-TD for lng-odp@lists.linaro.org; Wed, 17 Dec 2014 20:12:17 +0000 Received: by mail-qa0-f47.google.com with SMTP id s7so11460622qap.20 for ; Wed, 17 Dec 2014 12:12:12 -0800 (PST) X-Received: by 10.229.140.72 with SMTP id h8mr49873882qcu.25.1418847132455; Wed, 17 Dec 2014 12:12:12 -0800 (PST) Received: from localhost.localdomain ([98.221.136.245]) by mx.google.com with ESMTPSA id v8sm4824912qaf.12.2014.12.17.12.12.11 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 17 Dec 2014 12:12:11 -0800 (PST) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Wed, 17 Dec 2014 15:12:04 -0500 Message-Id: <1418847124-17288-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.1.0 X-Topics: Architecture patch Subject: [lng-odp] [PATCH ARCH] add doxygen_guide_lines X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: lng-odp-bounces@lists.linaro.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: mike.holmes@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.44 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 Clarify the guide lines around using doxygen to document the ODP API. Signed-off-by: Mike Holmes Reviewed-by: Bill Fischofer --- doxygen_guide_lines.dox | 54 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 doxygen_guide_lines.dox diff --git a/doxygen_guide_lines.dox b/doxygen_guide_lines.dox new file mode 100644 index 0000000..f76da5a --- /dev/null +++ b/doxygen_guide_lines.dox @@ -0,0 +1,54 @@ +/* Copyright (c) 2014, Linaro Limited + + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + +@page doxygen_guide_lines Doxygen Guide Lines + +@tableofcontents + +@section doxygen_introduction Introduction +ODP uses doxygen http://www.stack.nl/~dimitri/doxygen/ to document the public API. +This guide lists the ODP best practices for using the doxygen features. + +@section function_parameters Function Parameters + +Every parameter to a function must be documented with the \@param tag. +The direction indicators should be used, [in],[out] and [in,out] with the following guide lines for pointer arguments:- + - [in] Can generally be dropped, but indicates that data pre populated at the pointed to location is required by the function + - [out] Indicates that the function will populate the pointed to location with a result + - [in,out] Indicates that the location contains information used by the function, and it will populate the location with a result + +@section function_return Function return arguments + +Every function return other than void will be documented with \@return or \@retval with the following guide lines:- + - \@retval is used where a specific value is returned for a case or range of cases. + - For example retval would be used to specify that success is 0 and a failure to open a file returns -1 + @verbatim + @retval 0 on success + @retval -1 when the file cannot be opened + @endverbatim + - \@return is used where a range is described, but no specific returned value + - For example where a pointer to a structure is specified + @verbatim @return A pointer to the new structure @endverbatim + +In combination these may be used to detail specific return values that the implementation is expected to check for and document the general case. + +@verbatim +@return A pointer to the new structure +@retval NULL If the input arguments to the function are invalid +@retval NULL If the memory cannot be allocated +@endverbatim + +@section test_cases Documenting Test Cases +The \@retval tag has specific meaning for the test cases, an implementation of the ODP API is expected to conform to the behaviour specified by the retvals and unit tests should check that the behaviour exists. +In the above example test cases should try to prove that invalid input arguments or a failure to allocate memory return NULL. + +@section doxygen_errno Documenting errno +The \@retval tag also have specific meaning to the use of errno, these cases are the ones that should set errno to detail the specific reason, for example in the case above NULL is returned to indicate failure and errno should indicate which of the two failing cases has occurred. + +*/