mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Mark Vels <mark.vels@team-embedded.nl>
To: Sascha Hauer <s.hauer@pengutronix.de>
Cc: barebox@lists.infradead.org
Subject: Re: [RFC PATCH 0/9] Catch-up/clean-up doxygen documentation
Date: Thu, 03 Nov 2011 13:48:45 +0100	[thread overview]
Message-ID: <4EB28DAD.6010100@team-embedded.nl> (raw)
In-Reply-To: <20111103072645.GC16886@pengutronix.de>

Hi Sascha,

On 03-11-11 08:26, Sascha Hauer wrote:
> Thank you for your efforts, I really appreciate this. I hoped though
> that I can shift over the documentation to
> http://wiki.barebox.org/doku.php as this is maintainable without
> patching the source code. 
Is this to decrease your work load as maintainer or do you have other concerns that drive this goal?
> So I wonder if you didn't know about this
> website at all (could be my bad, I should have communicated this more
> clearly) or are there other problems with the documentation in the wiki?
Well, of course I saw the wiki but looking at the command documentation I figured it was older and less complete that
what I found in the generated documentation. Therefore I drew the conclusion that the doxygen documentation was the
preferred option.
> Maybe in the end the doxygen documentation is more what people actually
> want?
IMHO it makes sense to have command and supported board info generated from the source code because I see a number of
advantages:
- Documentation is tied to the source code. If options for a command are changed, expect a patch for the documentation
with it. With some discipline from contributors and reviewers this keeps the doc in sync with the code. Since I don't
seem to have any possibility to edit the wiki myself yet, this looks like a good excuse to let the wiki bit rot and not
update the documentation.

- When in future situations branching (for LTS versions?) becomes relevant (there are companies that are still using
UBoot 1.1.6 for example), there will be different implementations or command sets implemented for different branches.
Since the doxygen code is generated from the sources it is always relevant/ up-to-date for the version people are using.
I think having multiple versions documented is very hard and messy to realise with a wiki.

- It saves work to use doxygen since most information needs to be in the source code for the builtin help anyway.
Re-using it for the doxygen documentation (by using the BAREBOX_CMD_HELP_XXX() macros) is more efficient than having to
update the wiki too.

- I know that in the ideal world all changes go through upstream. But having worked at a number of big companies, there
will be all sorts of custom hacks to barebox that are not even relevant to be ever upstreamed (like commands to change
settings in custom FPGA firmware for example). The doxygen documentation can be a great framework to extend with
'home-brew' changes and documentation and make it easier to use barebox in such environments.

For the other documentation (the stuff in section 'Developer' section on the wiki etc), I don' really have a strong
opinion. Maybe the wiki is more convenient here because it has a more powerful and versatile syntax. I just wonder how
contributors to any wiki documentation should progress? Should they post the wiki-formatted pages to the mailing list?
Or are you planning on providing people with login credentials for the wiki on request?

In case we decide to stick with the wiki-only approach, I think it is time to do some clean-up in the source tree and
remove obsolete doxygen pages/comments. Would it make sense to create a DOCUMENTATION file manifest to explain the
documentation strategy?

Best regards,

Mark



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

  reply	other threads:[~2011-11-03 12:48 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
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
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 [this message]
2011-11-04  9:06     ` 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=4EB28DAD.6010100@team-embedded.nl \
    --to=mark.vels@team-embedded.nl \
    --cc=barebox@lists.infradead.org \
    --cc=s.hauer@pengutronix.de \
    /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