mail archive of the barebox mailing list
 help / color / mirror / Atom feed
* [RFC PATCH 0/9] Catch-up/clean-up doxygen documentation
@ 2011-11-01 10:09 Mark Vels
  2011-11-01 10:09 ` [PATCH 1/9] trivial: relocate doxygen help page for time command Mark Vels
                   ` (9 more replies)
  0 siblings, 10 replies; 13+ messages in thread
From: Mark Vels @ 2011-11-01 10:09 UTC (permalink / raw)
  To: barebox

I just started using BB and was a little anoyed by the fact that although there
is plenty of documentation in the source code, it did not show up in the
generated documentation. I think the availability of simple, clean and
structured information is important for the success of BB and make it 
enjoyable for developers to get aquainted with BB. Therefore I put some effort
in getting the doxygen output up to date.

This patch set tries to update the shell command documentation.

A short summary of the changes in this patch set:
- The first few patches deal with orphan pages; pages that were not
  linked to directly and hence showed up at top-level in the Doxygen output
  HTML.

- In the command overview page, a separation between platform-independent
  and dependent code has been made. In some cases I found 3 versions/
  implementations of the same command on different ARCHs, including 3 copies
  of the same documentation. I will try to come up with a solution for this
  and make sure we have consistent command implementations across different
  platforms and architectures which IMHO is important.

- In a few cases I found the command help information inside an #ifdef. I took
  the liberty to move the BAREBOX_CMD_HELP_* macros outside these conditional
  sections so that the documentation for that command always shows up in the
  Doxygen-generated output. Of course the availability of the commands and the
  help text in bb should not have been altered.

- An attempt is made to make consistent use of the BAREBOX_CMD_HELP_* macro's.
  Also some clean-up was done or small amendments to the documentation.

- I changed a number of syntax errors in the drivers/mtd/nand directory. It was
  not my intention to touch source-generated documentation but decided to fix a
  number of syntax errors to make a first attempt to get rid of all Doxygen 
  warnings and make the output usable again.

- I also tried to make sure all shell command documentation now uses the same
  format for describing cli options (for example the use of [OPTIONS] for 
  options and [<arg1>] for an optional argument. This style is what I saw
  for most commands already so I just tried to make it's use consistent.

I realise that the distribution of the number of changes is not optimal,
this patch set grew considerably bigger as I progressed. In the end it is
just a big collection of lots of small and trivial changes and I hope you can 
still find the motivation to review these patches and provide me with some 
feedback.

Thanks in advance!

Mark

Mark Vels (9):
  trivial: relocate doxygen help page for time command
  trivial: relocate doxygen help page for led command
  trivial: reorganize crc32 command doxygen output
  trivial: fix doxygen error in dlink-dir-320.dox
  trivial: De-orphan NAND doxygen output and fix @param syntax
  docs: Enable BAREBOX_CMD_HELP_TEXT() in generated documentation
  doxygen: Enable LONGHELP output in generated output
  trivial: Small change in page link title
  help: update of shell commands doxygen/online help documentation

 Documentation/commands.dox                        |  158 ++++++++++++---------
 Documentation/developers_manual.dox               |    2 +-
 Documentation/manual_org.dox                      |    2 +-
 Doxyfile                                          |    3 +-
 arch/arm/boards/eukrea_cpuimx35/eukrea_cpuimx35.c |   11 ++
 arch/arm/boards/guf-cupid/board.c                 |   11 ++
 arch/arm/boards/pcm043/pcm043.c                   |   11 ++
 arch/arm/cpu/cpu.c                                |   13 ++-
 arch/arm/cpu/cpuinfo.c                            |   10 ++
 arch/arm/lib/bootu.c                              |   11 ++-
 arch/arm/lib/bootz.c                              |   12 ++-
 arch/arm/mach-imx/clko.c                          |   17 ++-
 arch/arm/mach-imx/internal-nand-boot.c            |   15 ++-
 arch/arm/mach-imx/speed.c                         |   15 ++-
 arch/arm/mach-mxs/imx.c                           |   11 ++
 arch/arm/mach-netx/generic.c                      |   10 ++
 arch/blackfin/boards/ipe337/cmd_alternate.c       |   10 ++
 arch/mips/boards/dlink-dir-320/dlink-dir-320.dox  |    2 +-
 arch/mips/lib/cpuinfo.c                           |   10 ++
 commands/bmp.c                                    |   18 +--
 commands/bootm.c                                  |   25 ++--
 commands/cat.c                                    |    8 +-
 commands/cd.c                                     |    4 +
 commands/clear.c                                  |    5 +
 commands/cp.c                                     |   13 +-
 commands/crc.c                                    |   13 ++-
 commands/dfu.c                                    |   18 ++-
 commands/echo.c                                   |   19 ++-
 commands/edit.c                                   |   13 +-
 commands/exec.c                                   |   10 ++
 commands/export.c                                 |    5 +
 commands/false.c                                  |   17 +++
 commands/flash.c                                  |   75 +++++-----
 commands/go.c                                     |   16 ++-
 commands/gpio.c                                   |   19 +++
 commands/help.c                                   |   18 ++-
 commands/i2c.c                                    |   53 +++++---
 commands/insmod.c                                 |   12 ++-
 commands/led.c                                    |   16 ++-
 commands/loadb.c                                  |   35 ++++-
 commands/login.c                                  |   14 ++-
 commands/ls.c                                     |    5 +
 commands/lsmod.c                                  |   10 ++
 commands/mem.c                                    |  137 +++++++++++-------
 commands/meminfo.c                                |   10 ++
 commands/memtest.c                                |   22 ++-
 commands/menu.c                                   |  123 ++++++++--------
 commands/mkdir.c                                  |   14 ++-
 commands/mount.c                                  |   21 ++--
 commands/nand.c                                   |   18 ++-
 commands/net.c                                    |   21 +++-
 commands/partition.c                              |   33 +++--
 commands/passwd.c                                 |   13 +-
 commands/printenv.c                               |   11 +-
 commands/pwd.c                                    |    9 ++
 commands/readline.c                               |   12 +-
 commands/reginfo.c                                |    9 ++
 commands/reset.c                                  |   11 ++
 commands/rm.c                                     |   13 ++-
 commands/rmdir.c                                  |   14 ++-
 commands/sleep.c                                  |   15 ++-
 commands/test.c                                   |   16 ++-
 commands/time.c                                   |   10 +-
 commands/timeout.c                                |   22 ++-
 commands/trigger.c                                |    5 +
 commands/true.c                                   |   12 ++
 commands/ubi.c                                    |   38 ++++--
 commands/umount.c                                 |   12 ++-
 commands/unlzo.c                                  |   12 ++-
 commands/usb.c                                    |   12 ++-
 commands/version.c                                |    9 ++
 common/command.c                                  |   11 ++-
 common/hush.c                                     |   69 +++++-----
 drivers/base/driver.c                             |   28 ++--
 drivers/led/led-triggers.c                        |    2 +-
 drivers/mtd/nand/nand_bbt.c                       |   14 ++-
 drivers/mtd/nand/nand_hwecc_syndrome.c            |   44 ++++---
 drivers/mtd/nand/nand_omap_bch_decoder.c          |   19 ++-
 drivers/mtd/nand/nand_write.c                     |  136 +++++++++---------
 include/command.h                                 |    2 +-
 net/dhcp.c                                        |   10 ++
 net/dns.c                                         |   11 ++-
 net/nfs.c                                         |   12 ++-
 net/ping.c                                        |   12 ++
 net/tftp.c                                        |   21 ++--
 85 files changed, 1212 insertions(+), 608 deletions(-)


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2011-11-04  9:06 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-11-01 10:09 [RFC PATCH 0/9] Catch-up/clean-up doxygen documentation Mark Vels
2011-11-01 10:09 ` [PATCH 1/9] trivial: relocate doxygen help page for time command Mark Vels
2011-11-01 10:09 ` [PATCH 2/9] trivial: relocate doxygen help page for led command Mark Vels
2011-11-01 10:09 ` [PATCH 3/9] trivial: reorganize crc32 command doxygen output Mark Vels
2011-11-01 10:09 ` [PATCH 4/9] trivial: fix doxygen error in dlink-dir-320.dox Mark Vels
2011-11-01 10:09 ` [PATCH 5/9] trivial: De-orphan NAND doxygen output and fix @param syntax Mark Vels
2011-11-01 10:09 ` [PATCH 6/9] docs: Enable BAREBOX_CMD_HELP_TEXT() in generated documentation Mark Vels
2011-11-01 10:09 ` [PATCH 7/9] doxygen: Enable LONGHELP output in generated output Mark Vels
2011-11-01 10:09 ` [PATCH 8/9] trivial: Small change in page link title Mark Vels
2011-11-01 10:09 ` [PATCH 9/9] help: update of shell commands doxygen/online help documentation Mark Vels
2011-11-03  7:26 ` [RFC PATCH 0/9] Catch-up/clean-up doxygen documentation Sascha Hauer
2011-11-03 12:48   ` Mark Vels
2011-11-04  9:06     ` Sascha Hauer

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox