From patchwork Wed Oct 23 13:12:53 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gabriela Bittencourt X-Patchwork-Id: 11206783 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9E8AE913 for ; Wed, 23 Oct 2019 13:13:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 730EE21872 for ; Wed, 23 Oct 2019 13:13:12 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="OQbB3ahk" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2405688AbfJWNNM (ORCPT ); Wed, 23 Oct 2019 09:13:12 -0400 Received: from mail-qt1-f194.google.com ([209.85.160.194]:39355 "EHLO mail-qt1-f194.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732284AbfJWNNL (ORCPT ); Wed, 23 Oct 2019 09:13:11 -0400 Received: by mail-qt1-f194.google.com with SMTP id t8so14626269qtc.6; Wed, 23 Oct 2019 06:13:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=ohRiKoQhkRpaqt9hJhdQvzQzR+t9Fsg+JL8RFCA1XEE=; b=OQbB3ahkNcYiRxKZW8WuEY2S5xKzEhTNB/yLXCb1NRI8+c7ma5fAM9xNufogBcCpNg V5siEzpBSch8ntre1ZdrN8kiOhhZX8AIUIELqxg5XWp11+Wn6SMTVEtWb7T2sKxwiCn0 AQxaWPGf9ayNFpQPdasmdYfV4vXuSjxaqeI9mN4kSB6ETuY4xI+Cotu/jBQHp22f94va p/daWLWBPAxV9x2V2EwGYeMLWAj69yJelgOqu+70IE33ofgUlvNXfugBhApkps3Og5rD EWc6s2CMCuPgPeMhpAWbVIbo0Y6+/csSEDR85pxw0Ixxi3LOUdDn46zToyKDyl/Y9Rkm rUyg== 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:mime-version:content-transfer-encoding; bh=ohRiKoQhkRpaqt9hJhdQvzQzR+t9Fsg+JL8RFCA1XEE=; b=DoIz3spvPkLtDquuEb/8qiz4ilIodeCmq1bzhkJTr88exROWR1baoRj87140eMkapC ec13RXHBDDsat61gHQ6782bFbYJ+exYL4Q43URW3ZAr8jDRlHBpvjtiA3ryTAZ8PQYRQ LPFmVGP+JkpDwG3HHOc78seS+YG1NDY6a9i3/nDI7nVmyBvDRMJcdCo2hKQTasJevNFZ 5XJrjC9nyttlUl2JijW7bmHvM6P4G3bFTZmKm7yRkobR1Xz4dsE/1Y3TTBhw2IzVj6y+ CDeKLmlJmwVnioRgSfrdpD9tm9vjsrRSFRxnM5iVVh4zGkPxBJHM7qczTJP95MMAbSn5 NrGw== X-Gm-Message-State: APjAAAWde9d6OD8yQ9zSx7gms6fLDA07im8Z+jwrfV8ts++P4x7ire9R Bp/6HGsq0A4YY0IB05dVQDs= X-Google-Smtp-Source: APXvYqxUNw3eGYQPCjmEl+DfjUt6gNVhcVwP5JaM+9whBAfh/v4ApQcotxJJS9TmAmZJoSI+LPypCQ== X-Received: by 2002:aed:3063:: with SMTP id 90mr7472229qte.242.1571836390299; Wed, 23 Oct 2019 06:13:10 -0700 (PDT) Received: from localhost.localdomain ([201.53.210.37]) by smtp.gmail.com with ESMTPSA id p22sm9863919qkk.92.2019.10.23.06.13.07 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 23 Oct 2019 06:13:09 -0700 (PDT) From: Gabriela Bittencourt To: outreachy-kernel@googlegroups.com, sudipm.mukherjee@gmail.com, teddy.wang@siliconmotion.com, gregkh@linuxfoundation.org, linux-fbdev@vger.kernel.org, devel@driverdev.osuosl.org, linux-kernel@vger.kernel.org, lkcamp@lists.libreplanetbr.org Cc: Gabriela Bittencourt Subject: [PATCH v2] staging: sm750fb: Format description of parameters the to kernel doc format Date: Wed, 23 Oct 2019 10:12:53 -0300 Message-Id: <20191023131253.20819-2-gabrielabittencourt00@gmail.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20191023131253.20819-1-gabrielabittencourt00@gmail.com> References: <20191023131253.20819-1-gabrielabittencourt00@gmail.com> MIME-Version: 1.0 Sender: linux-fbdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fbdev@vger.kernel.org Cluster comments that describes parameters of functions and create one single comment before the function in kernel doc format. Signed-off-by: Gabriela Bittencourt --- Changes v2: - Add name of function at the begining of comment - Separate each parameter in individuals lines Here are the commands that I used to test my documentation and the respective outputs: $ kdoc_function sm750_acc.c sm750_hw_imageblit man In NAME: there is the name of the function, but it's without a brief description In ARGUMENTS: argument 'accel' is presented as '-- undescribed --' $ kdoc_function sm750_acc.c sm750_hw_copyarea man In NAME: there is the name of the function, but it's without a brief description In ARGUMENTS: argument 'accel' is presented as '-- undescribed --' $ kernel-doc -none sm750_accel.c 2 Warnings: sm750_accel.c:155: warning: Function parameter or member 'accel' not described in 'sm750_hw_copyarea' sm750_accel.c:321: warning: Function parameter or member 'accel' not described in 'sm750_hw_imageblit' I appreciate Randy's explanation about how to test documentation. Thank you very much. --- drivers/staging/sm750fb/sm750_accel.c | 72 ++++++++++++++++----------- 1 file changed, 44 insertions(+), 28 deletions(-) diff --git a/drivers/staging/sm750fb/sm750_accel.c b/drivers/staging/sm750fb/sm750_accel.c index dbcbbd1055da..645813a87490 100644 --- a/drivers/staging/sm750fb/sm750_accel.c +++ b/drivers/staging/sm750fb/sm750_accel.c @@ -130,20 +130,28 @@ int sm750_hw_fillrect(struct lynx_accel *accel, return 0; } -int sm750_hw_copyarea( -struct lynx_accel *accel, -unsigned int sBase, /* Address of source: offset in frame buffer */ -unsigned int sPitch, /* Pitch value of source surface in BYTE */ -unsigned int sx, -unsigned int sy, /* Starting coordinate of source surface */ -unsigned int dBase, /* Address of destination: offset in frame buffer */ -unsigned int dPitch, /* Pitch value of destination surface in BYTE */ -unsigned int Bpp, /* Color depth of destination surface */ -unsigned int dx, -unsigned int dy, /* Starting coordinate of destination surface */ -unsigned int width, -unsigned int height, /* width and height of rectangle in pixel value */ -unsigned int rop2) /* ROP value */ +/** + * sm750_hm_copyarea + * @sBase: Address of source: offset in frame buffer + * @sPitch: Pitch value of source surface in BYTE + * @sx: Starting x coordinate of source surface + * @sy: Starting y coordinate of source surface + * @dBase: Address of destination: offset in frame buffer + * @dPitch: Pitch value of destination surface in BYTE + * @Bpp: Color depth of destination surface + * @dx: Starting x coordinate of destination surface + * @dy: Starting y coordinate of destination surface + * @width: width of rectangle in pixel value + * @height: height of rectangle in pixel value + * @rop2: ROP value + */ +int sm750_hw_copyarea(struct lynx_accel *accel, + unsigned int sBase, unsigned int sPitch, + unsigned int sx, unsigned int sy, + unsigned int dBase, unsigned int dPitch, + unsigned int Bpp, unsigned int dx, unsigned int dy, + unsigned int width, unsigned int height, + unsigned int rop2) { unsigned int nDirection, de_ctrl; @@ -288,20 +296,28 @@ static unsigned int deGetTransparency(struct lynx_accel *accel) return de_ctrl; } -int sm750_hw_imageblit(struct lynx_accel *accel, - const char *pSrcbuf, /* pointer to start of source buffer in system memory */ - u32 srcDelta, /* Pitch value (in bytes) of the source buffer, +ive means top down and -ive mean button up */ - u32 startBit, /* Mono data can start at any bit in a byte, this value should be 0 to 7 */ - u32 dBase, /* Address of destination: offset in frame buffer */ - u32 dPitch, /* Pitch value of destination surface in BYTE */ - u32 bytePerPixel, /* Color depth of destination surface */ - u32 dx, - u32 dy, /* Starting coordinate of destination surface */ - u32 width, - u32 height, /* width and height of rectangle in pixel value */ - u32 fColor, /* Foreground color (corresponding to a 1 in the monochrome data */ - u32 bColor, /* Background color (corresponding to a 0 in the monochrome data */ - u32 rop2) /* ROP value */ +/** + * sm750_hw_imageblit + * @pSrcbuf: pointer to start of source buffer in system memory + * @srcDelta: Pitch value (in bytes) of the source buffer, +ive means top down + * and -ive mean button up + * @startBit: Mono data can start at any bit in a byte, this value should be + * 0 to 7 + * @dBase: Address of destination: offset in frame buffer + * @dPitch: Pitch value of destination surface in BYTE + * @bytePerPixel: Color depth of destination surface + * @dx: Starting x coordinate of destination surface + * @dy: Starting y coordinate of destination surface + * @width: width of rectangle in pixel value + * @height: height of rectangle in pixel value + * @fColor: Foreground color (corresponding to a 1 in the monochrome data + * @bColor: Background color (corresponding to a 0 in the monochrome data + * @rop2: ROP value + */ +int sm750_hw_imageblit(struct lynx_accel *accel, const char *pSrcbuf, + u32 srcDelta, u32 startBit, u32 dBase, u32 dPitch, + u32 bytePerPixel, u32 dx, u32 dy, u32 width, + u32 height, u32 fColor, u32 bColor, u32 rop2) { unsigned int ulBytesPerScan; unsigned int ul4BytesPerScan;