Re: [dpdk-dev] [PATCH 1/3] ether: Update field name and description for queue start

[Stephen Hemminger <stephen@networkplumber.org>]

On Tue, 22 Jul 2014 15:47:30 +0800
Ouyang Changchun <changchun.ouyang@intel.com> wrote:

> +	/**< If rx_enable_queue is true, rte_eth_dev_rx_queue_start must be
> +		invocated after rte_eth_dev_start's invocation to start RX for
> +		one queue, and rte_eth_dev_rx_queue_start instead of
> +		rte_eth_dev_start is responsible for allocating mbuf from
> +		mempool and setup the DMA physical address. It is useful in
> +		such scenario: buffer address is not available at the point of
> +		rte_eth_dev_start's invocation but available later, e.g. in
> +		VHOST zero copy case, the buffer address to be setup DMA
> +		address is available only after one VM startup. */

Good documentation about semantics is really valuable as long as it
kept up to date. In this case, the comment stands out which is not
a good thing.

An explanation this long belongs in documentation not in code.
Alternatively, if it is this hard to explain maybe it isn't the right design :-)