[U-Boot] [RFC 2/3] uboot-doc: Add example support for uboot-doc

[Wolfgang Denk]

Dear John Schmoller,

In message <310e8398479f23a6bfaceccf6cc86631b7bff4dc.1248798202.git.jschmoller at xes-inc.com> you wrote:
> Add support to a small subset of commands, environment
> variables, and POSTs. These are meant to show the
> syntax and capabilities of the uboot-doc parser.
> 
> Signed-off-by: John Schmoller <jschmoller at xes-inc.com>
> ---
>  common/cmd_i2c.c    |   71 ++++++++++++++++++++++++++++++++++++++++++++++++++-
>  common/cmd_mem.c    |   45 +++++++++++++++++++++++++++++++-
>  common/cmd_net.c    |   30 ++++++++++++++++++++-
>  common/env_common.c |   35 +++++++++++++++++++++++++
>  post/tests.c        |   16 +++++++++++
>  5 files changed, 192 insertions(+), 5 deletions(-)
> 
> diff --git a/common/cmd_i2c.c b/common/cmd_i2c.c
> index 8f0fc9e..14d394c 100644
> --- a/common/cmd_i2c.c
> +++ b/common/cmd_i2c.c
> @@ -1297,7 +1297,70 @@ int do_i2c(cmd_tbl_t * cmdtp, int flag, int argc, char *argv[])
>  }
>  
>  /***************************************************/
> -
> +/**
> + * @cmd: i2c speed
> + * @sect: I2C
> + * @param[or]: speed - target I2C bus speed
> + * @desc: Show or set I2C bus speed
> + */
> +/**
> + * @cmd: i2c dev
> + * @sect: I2C
> + * @param[or]: dev - I2C device to make current
> + * @desc: Show or set current I2C bus
> + */
> +/**
> + * @cmd: i2c md
> + * @sect: I2C
> + * @param: chip - I2C address of desired device
> + * @param: address[.0, .1, .2] - Address into I2C device
> + * @param[or]: # of objects - Numer of bytes to read
> + * @desc: Read from I2C device
> + */
> +/**
> + * @cmd: i2c mm
> + * @sect: I2C
> + * @param: chip - I2C address of desired device
> + * @param: address[.0, .1, .2] - Address into I2C device
> + * @desc: Write to I2C device (auto-incrementing)
> + */
> +/**
> + * @cmd: i2c mw
> + * @sect: I2C
> + * @param: chip - I2C address of desired device
> + * @param: address[.0, .1, .2] - Address into I2C device
> + * @param: value - Value to write to I2C address
> + * @param[or]: count - Number of bytes to write
> + * @desc: Write to I2C device (fill)
> + */
> +/**
> + * @cmd: i2c nm
> + * @sect: I2C
> + * @param: chip - I2C address of desired device
> + * @param: address[.0, .1, .2] - Address into I2C device
> + * @desc: Write to I2C device (constant address)
> + */
> +/**
> + * @cmd: i2c crc32
> + * @sect: I2C
> + * @param: chip - I2C address of desired device
> + * @param: address[.0, .1, .2] - Address into I2C device
> + * @param: count - Number of bytes to CRC
> + * @desc: Computes the CRC32 checksum of an address range
> + */
> +/**
> + * @cmd: i2c probe
> + * @sect: I2C
> + * @desc: Shows all the devices on the I2C bus
> + */
> +/**
> + * @cmd: i2c loop
> + * @sect: I2C
> + * @param: chip - I2C address of desired device
> + * @param: address[.0, .1, .2] - Address into I2C device
> + * @param: # of objects - Number of bytes to loop over
> + * @desc: Looping read of device.  Never returns.
> + */

Hm... isn't this basicly duplicating the information you get when
running the "help" command? Then why don't you simply include that
output here, like we do in the DULG?

To me this seems to be a mix of API documentation (which would be
useful, but you do it for the wrong set of functions) and User's
Manual (where it mostly seems to be a duplication of information, and
maintaining redundant information has never been a good idea).

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
It's certainly  convenient  the  way  the  crime  (or  condition)  of
stupidity   carries   with   it  its  own  punishment,  automatically
admisistered without remorse, pity, or prejudice. :-)
         -- Tom Christiansen in <559seq$ag1$1 at csnews.cs.colorado.edu>