[U-Boot] organizing doc/ dir?

[Albert ARIBAUD]

Hi Kumar and others,

Le 23/02/2011 07:02, Kumar Gala a écrit :
> Wolfgang,
>
> Any issue that added a little hierarchy to the doc/ dir?
>
> maybe something mimic board/

I would tend to agree wholeheartedly to the idea, if only because /doc 
currently contains 154 files, which meakes it not that easy to sort 
things out.

But why limit oneself to boards? U-Boot has a structured arch/ dir as 
well, and lib/ also, to name only some. Structuring /doc after these as 
well would be quite useful as:

- only general U-Boot doc files would reside directly under /doc, making 
it easier for beginners to grasp U-boot essentials (and for seasoned 
users to brush up their knowledge) -- for instance, the rationales for 
U-Boot such as the recently discussed float issue could be made much 
more visible by being one of a few files in /doc itself;

- arch-related files under /doc/arch (including a rationale file 
explaining how /arch itself is organized) and arch-specific files under 
/doc/arch/<arch> -- /doc/arch/arm would hold all ARM related stuff; that 
would make arch, cpu, SoC specific information easier to locate;

- lib-related files in /doc/lib to better explain and document the "as 
much of libc behavior as needed but no more" approach;

- possibly even on a far further future, automated doc generation from 
code annotations would help keeping the doc up-to-date and benefit from 
/doc mimicking the source code tree structure -- but granted, it may not 
be that easy to find where in the code some of what /doc contains now 
should go.

... and I'm certainly missing other benefits.

So yes, I would second a /doc reorg beyond a mere /doc/boards creation.

Amicalement,
-- 
Albert.