From mboxrd@z Thu Jan  1 00:00:00 1970
From: Shreyansh Jain <shreyansh.jain@nxp.com>
Subject: Re: [PATCH v1 3/5] drivers/raw: introduce skeleton
	rawdev driver
Date: Tue, 16 Jan 2018 15:51:27 +0530
Message-ID: <a676ec2d-6c1e-2109-7b3a-9f287ea3ea76@nxp.com>
References: <20180102125749.2379-1-shreyansh.jain@nxp.com>
 <20180102125749.2379-4-shreyansh.jain@nxp.com> <3616426.fmUHyIAH1S@xps>
Mime-Version: 1.0
Content-Type: text/plain; charset="utf-8"; format=flowed
Content-Transfer-Encoding: 7bit
Cc: <dev@dpdk.org>, <hemant.agrawal@nxp.com>, <fiona.trahe@intel.com>,
 <rosen.xu@intel.com>
To: Thomas Monjalon <thomas@monjalon.net>
Return-path: <dev-bounces@dpdk.org>
Received: from NAM01-SN1-obe.outbound.protection.outlook.com
 (mail-sn1nam01on0082.outbound.protection.outlook.com [104.47.32.82])
 by dpdk.org (Postfix) with ESMTP id BD5902BB5
 for <dev@dpdk.org>; Tue, 16 Jan 2018 11:07:17 +0100 (CET)
In-Reply-To: <3616426.fmUHyIAH1S@xps>
Content-Language: en-US
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://dpdk.org/ml/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://dpdk.org/ml/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

On Monday 15 January 2018 04:24 AM, Thomas Monjalon wrote:
> 02/01/2018 13:57, Shreyansh Jain:
>> +struct skeleton_firmware {
>> +	struct skeleton_firmware_version_info firmware_version;
>> +	/**< Device firmware information */
>> +	enum skeleton_firmware_state firmware_state;
>> +	/**< Device state */
>> +};
>> +
>> +#define SKELETON_MAX_ATTRIBUTES 10
>> +#define SKELETON_ATTRIBUTE_NAME_MAX 20
>> +
>> +struct skeleton_rawdev_attributes {
>> +	char *name;
>> +	/**< Name of the attribute */
>> +	uint64_t value;
>> +	/**< Value or reference of value of attribute */
>> +};
>> +
>> +#define SKELETON_CAPA_FW_LOAD	0x0001
>> +/**< Device supports firmware loading/unloading */
>> +#define SKELETON_CAPA_FW_RESET  0x0002
>> +/**< Device supports firmware reset */
>> +#define SKELETON_CAPA_QUEUES    0x0004
>> +/**< Device support queue based communication */
> 
> Comment about the style. The style is important :)
> You are always writing comments after the item.

Yes, I was trying to stick to single method - postfix.

> When comments are on a separate line, I think it is preferred to write
> them *before* the item they describe.
> 

Consider this:

struct dummy {
     int a;  /**< a postfix comment */
     /**< a prefix comment */
     int b;
};

Personally, Even I prefer prefix when it comes to full line comments - 
but mixing prefix and postfix can lead to non-readable code.

Anyways - I was referring [1]

[1] 
http://dpdk.org/doc/guides/contributing/documentation.html#doxygen-guidelines

and it seems that I should change all to prefix in case any comment in 
the structure is not fitting into a single line.
I will do that.

Regards,
Shreyansh