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

jschmoller
2009-07-28T20:42:29Z

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