Re: [doc] Update gimple_statement_with_ops and gimple_statement_with_memory_ops

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Wed, 28 Apr 2010, Manuel López-Ibáñez wrote:

> On 28 April 2010 00:29, Joseph S. Myers <joseph@codesourcery.com> wrote:
> > On Tue, 27 Apr 2010, Manuel López-Ibáñez wrote:
> >
> > We have been waiting for some time for the FSF to produce license
> > exception wording to allow text extracted from the sources to be combined
> > with text in the internals manual.
> > <http://gcc.gnu.org/ml/gcc/2010-01/msg00342.html> was confirmation that
> 
> That method seems like an ad-hoc solution that will be hard to extend
> for all GCC internals.

Hopefully people can come up with more general solutions where merited (I 
can imagine a single solution for almost all cases where the aim is to 
extract a function prototype and text documenting that function, for 
example).

I think the principle is right that there should be a mixture of text 
written directly in the manual, providing overall structure and overview 
and pieces that aren't API documentation, and API documentation extracted 
from the definition of those APIs, with appropriate guidance to put that 
API documentation in logically appropriate places in the manual (a manual 
people can and do read straight through) rather than as a massive dump 
only sorted by source location or alphabetically.  In the absence of 
patches to achieve such integration, tools such as doxygen may of course 
be useful to extract information about APIs in areas not presently covered 
in the internals manual at all, as may doxygen markup (which might later 
be automatically converted to Texinfo).

(It's not just internals; a similar case might apply for having options 
documentation go in the .opt files, and from there end up in the user 
manual, from which texi2pod is in turn used to generate a man page.  And I 
don't see how you avoid an ad hoc solution when dealing with GCC-specific 
options handling.)

-- 
Joseph S. Myers
joseph@codesourcery.com