mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Holger Schurig <holgerschurig@gmail.com>
To: Antony Pavlov <antonynpavlov@gmail.com>
Cc: barebox@lists.infradead.org
Subject: Re: [PATCH 08/19] commands: move CMD_MIPS_CPUINFO to commands/Kconfig
Date: Tue, 13 May 2014 14:43:38 +0200	[thread overview]
Message-ID: <CAOpc7mG43m7qnMq20DG0_nZhWFnSzDUfjUuZ9T3t61Q1p=AtaQ@mail.gmail.com> (raw)
In-Reply-To: <20140513162340.c2689ed174c2ad441edceab1@gmail.com>

> Can we move example 'cpuinfo' output to *.dox?

That can be done, but it is not done by me. The doxygen is in such a
bad state, that I'm not really wanting to work on it. How many
commands are in doxygen? How sorted are they, how complete are they?
Not even concepts like memory area etc are currently described nicely
there.

Also, when I was doing "make xconfig" and wanted to select the
options, I was looking into the xconfig program, not in some
(suboptimal) doxygen docs. So I think the documentation for this step
should be in the Kconfig in the first place, everything else is then
optional.



If it would be to me, I'd in long-term kill the doxygen. Or have the
doxygen only describe the internal API for barebox programmers.
Currently it mixes internal API and end-user documention, not so nice.

Finally, ideally there would be only one place with command
descriptions (currently we have three: BAREBOX_CMD_FOO macros, Kconfig
entries, doxygen comments). It would be nice if the BAREBOX_FOO ones
become the main one, and that other ones be automatically generated
from them. There could even be a BAREBOX_CMD_HELP_DOXY() macro for
text that just ends up in the doxyfile, but not in the barebox binary.

In fact I already have done a first step towards this. My
not-yet-published scripts/checkhelp.py program. It parses all the *.c
file recursively for the BAREBOX_CMD_foo macros, and checks for
various things (e.g. line length not > 77 characters). As this script
already parses the stuff, it could also be used store information and
output into some different format.

However, priority-wise I still think that all Kconfig entries (for
non-commands) without a help text should get one first, this is more
helpful than some long documentation file. And that barebox develops a
policy where patch with a new Kconfig but without a good documention
would simply be rejected.

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

  reply	other threads:[~2014-05-13 12:44 UTC|newest]

Thread overview: 35+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2014-05-13  8:28 [PATCH 00/19] commands rework patch series Holger Schurig
2014-05-13  8:28 ` [PATCH 01/19] commands: group 'help' output Holger Schurig
2014-05-13 13:48   ` Sascha Hauer
2014-05-13 14:07     ` Holger Schurig
2014-05-13  8:28 ` [PATCH 02/19] commands: harmonize in-barebox documentation Holger Schurig
2014-05-13  8:28 ` [PATCH 03/19] commands: harmonize in-barebox docs with Kconfig docs Holger Schurig
2014-05-13  8:28 ` [PATCH 04/19] commands: CMD_MEMORY -> COMPILE_MEMORY Holger Schurig
2014-05-13  8:28 ` [PATCH 05/19] commands: CMD_DIGEST -> COMPILE_DIGEST Holger Schurig
2014-05-13  8:28 ` [PATCH 06/19] commands: move CMD_ARM_CPUINFO to commands/Kconfig Holger Schurig
2014-05-13  8:28 ` [PATCH 07/19] commands: move CMD_ARM_MMUINFO " Holger Schurig
2014-05-13  8:28 ` [PATCH 08/19] commands: move CMD_MIPS_CPUINFO " Holger Schurig
2014-05-13 11:26   ` Antony Pavlov
2014-05-13 11:28     ` Holger Schurig
2014-05-13 12:23       ` Antony Pavlov
2014-05-13 12:43         ` Holger Schurig [this message]
2014-05-13 13:09           ` Juergen Borleis
2014-05-13  8:28 ` [PATCH 09/19] commands: move CMD_BOOT_ORDER " Holger Schurig
2014-05-13  8:28 ` [PATCH 10/19] commands: move CMD_AT91_BOOT_TEST " Holger Schurig
2014-05-13  8:28 ` [PATCH 11/19] commands: move CMD_AT91MUX " Holger Schurig
2014-05-13  8:28 ` [PATCH 12/19] commands: move CMD_AT91MIX " Holger Schurig
2014-05-13  8:28 ` [PATCH 13/19] commands: HUSH_GETOPT -> CMD_GETOPT Holger Schurig
2014-05-13  8:28 ` [PATCH 14/19] commands: let all network commands depend on NET Holger Schurig
2014-05-13  8:28 ` [PATCH 15/19] commands: introduce CMD_HOST Holger Schurig
2014-05-13  8:28 ` [PATCH 16/19] commands: NET_PING -> CMD_PING Holger Schurig
2014-05-13  8:28 ` [PATCH 17/19] commands: NET_DHCP -> CMD_DHCP Holger Schurig
2014-05-13  8:28 ` [PATCH 18/19] commands: move CMD_IFUP to commands/Kconfig Holger Schurig
2014-05-13  8:28 ` [PATCH 19/19] commands: move CONFIG_LONGHELP " Holger Schurig
2014-05-13  8:30 ` [PATCH 00/19] commands rework patch series Holger Schurig
2014-05-13  8:41   ` Sascha Hauer
2014-05-13  9:00   ` Holger Schurig
2014-05-13 13:46 ` Sascha Hauer
2014-05-14  7:02 ` Sascha Hauer
2014-05-14 13:55   ` Antony Pavlov
2014-05-15  8:09     ` Holger Schurig
2014-05-15 11:52       ` Sascha Hauer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAOpc7mG43m7qnMq20DG0_nZhWFnSzDUfjUuZ9T3t61Q1p=AtaQ@mail.gmail.com' \
    --to=holgerschurig@gmail.com \
    --cc=antonynpavlov@gmail.com \
    --cc=barebox@lists.infradead.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox