This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

RE: Creating a live, all-encompassing architectural document for GCC


 

> -----Original Message-----
> From: Diego Novillo [mailto:dnovillo@google.com] 
> Sent: Friday, October 26, 2007 11:10 AM
> To: gcc@gcc.gnu.org
> Subject: RFC: Creating a live, all-encompassing architectural 
> document for GCC
> 
> 
> It should be easy for an individual maintainer (or even user) to go in
> and modify parts of the document that are incomplete/missing/wrong.
> This and navigability suggest a wikipedia-like approach.  We even have
> the beginnings of some of this in the wiki, so I would like to build
> on that.
...
> However, if
> a patch refactors a module and its internal interfaces are changed,
> then the patch should be accompanied with a change to the
> documentation.
... 
> The documentation for individual modules and files should be linked to
> the actual source code.  Perhaps this could be automatically generated
> with tools like javadoc or doxygen.
...
> So, I think my inclination is to provide this document as a wiki.

I like the goals. But what I see above seems mutually exclusive.

It's reasonable to include doxygen, and change the code with the
documentation simultaneously. Here's the avr-libc user manual online as an
example of the output:
<http://www.nongnu.org/avr-libc/user-manual/>
It certainly meets the navigable requirement. I'm sure all of you have seen
other examples as well.

But you also want the user to be able to change an internals document via a
wiki? How does this work with a patch system? How do you propose to resolve
conflicts between a user edit, and maintainer's patch? Maybe I'm ignorant to
the capabilities of a wiki, but this is where it sounds like incompatible
systems.

Eric Weddington


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]