barebox Documentation

[Antony Pavlov]

On Tue, 13 May 2014 15:42:28 +0200
Sascha Hauer <s.hauer at pengutronix.de> wrote:

> Hi,
> 
> As we all know the barebox documentation sucks. We @Pengutronix will
> have our internal techweek next month. One of the goals will be to
> improve the documentation situation for barebox.
> 
> What are your opinions in which form the documentation should be?
> 
> We currently have plain text files under Documentation/, a wiki on
> http://wiki.barebox.org/doku.php and doxygen. None of the documentation
> sets is complete and all are outdated.
> 
> Some pros and cons of the existing approaches are:
> 
> Plain text files
> + Easy to write
> + no extra step to generate docs, wysiwyg ;)
> - no links
> - no pictures
> 
> Wiki
> - not contained in the repository, so may be out of sync

http://en.wikipedia.org/wiki/Gitit_%28software%29 ?

> + links
> + nice markup language
>
> doxygen
> + contained in the repository
> + easy html doc generation
> + links
> - extra step to generate the docs

- not trivail board documentation adding (e.g. there is Documentation/boards.dox, and
there is arch/arm/mach-omap/arch-omap.dox too)

-- 
Best regards,
  Antony Pavlov