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

[jschmoller <jschmoller@xes-inc.com>]

On Tue, 2009-07-28 at 19:52 +0200, Wolfgang Denk wrote:
> Dear John Schmoller,
> 
> In message <310e8398479f23a6bfaceccf6cc86631b7bff4dc.1248798202.git.jschmoller@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@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).
> 

It's true, I was a little lax on commenting the I2C commands. If I were
to move forward with this documentation tool, I would comment these
commands more thoroughly like I did with the Memory commands.

Thanks,
John