`@return` is dedicated for brief description of return values, not for comments
stating actual return values. In addition, sphinx + breathe does not join
multiple adjacent `@return`. This results in multiple `Return` sections in the
generated document, which is confusing.
This patch replaces `@return` with `@retval` for the lists of return
values. Adjacent `@retval` can be joined into one list by breathe.
v1 -> v2:
* Replace return value descriptions like `negative` and `positive` with
expressions like `<0` and `>0` in `@retval`.
* Keep the list of `@retval` comprehensive, even when there is a `@return` to
generally describe what the return value means.
* Drop duplicated `@return` when it does not give more information than the
`@retval` list.
Tracked-On: #1595
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
These APIs are wrap of standard strto* APIs. The first parameters in
these APIs should be declared as "const" since they have never been
changed so that they can also be used when passing a variable declared
as const char *
Fixes: e1dab512c2 ("dm: add string convert API")
Tracked-on: #1496
Signed-off-by: Jie Deng <jie.deng@intel.com>
Reviewed-by: Conghui Chen <conghui.chen@intel.com>
Acked-by: Yu Wang <yu1.wang@intel.com>
As function sscanf is banned, to get value from parameter buffer,strto*
is recommended. To reduce the inspection code when using strto*, it's
better to use a string convert API.
Usage:
For virtio-blk, it has parameters:
range=<start lba>/<subfile size>
sscanf:
if (sscanf(cp, "range=%ld/%ld", &sub_file_start_lba,
&sub_file_size) == 2)
sub_file_assign = 1;
string API:
if (strsep(&cp, "=") &&
!dm_strtol(cp, &cp, 10, &sub_file_start_lba) &&
*cp == '/' &&
!dm_strtol(cp + 1, &cp, 10, &sub_file_size))
sub_file_assign = 1;
Tracked-on: #1496
Signed-off-by: Conghui Chen <conghui.chen@intel.com>
Reviewed-by: Shuo Liu <shuo.a.liu@intel.com>
Acked-by: Yin Fengwei <fengwei.yin@intel.com>
Junjie Mao