Re: [tree-ssa] cfg.texi needs reviewing by a native speaker (Was: Re: "Documentation by paper")

[Jan Hubicka <hubicka at ucw dot cz>]

> Joe Buck wrote:
> 
> >I could take a shot at a review for language.  Someone like Kenner would
> >be better suited than me to do a review for usability (by a front end
> >maintainer who must interface with tree-ssa), but if he doesn't want to
> >my review will be better than nothing.
> 
> I didn't see Richard say he would not review it, just that he would be
> happier if the documentation was in the source code (a view I share, but
> I am sure Richard agrees that doc in the doc is better than no doc at 
> all :-)

While originally writing the document, I was verifying that all the
information is present in some form in the comments too and fixed some
occurences where it wasn't (like missing docs for EDGE_* flags).  So the
information is in place, just spred across the function comments so I
think it is dificult to make sense of it when you are not sure for what
you are looking.

The documentaiton in code is meant to be specification of what
individual functions does, while the cfg.texi is meant to be more
concise overview of basic concepts.
the cfg code itself is organized into modules, each having overall
comment about the functionality provided, comments in before the
functions and headers documents the datastructures, yet it seems to not
be enough.

Perhaps predict.c deserve overview comment as it involve good amount of
magic even tought the first two papers are available on web and describe
almost exactly what it does.  I can add one.

I was also trying to avoid going into the greatest technicalities in the
cfg.texi document to make it easier to be up to date and just provide
oveview of the basic concepts.

Honza