Documentation Buglets

Documentation Buglets

[Stephan T. Lavavej]

I've noticed some small problems with gcc's documentation.

http://gcc.gnu.org/bugs.html#updating
> ABI bugs
> ...
> Covariant return types
> ... 
> GNATS PR 3706 tracks this problem.

3706 is closed for 3.4.

http://gcc.gnu.org/onlinedocs/gcc-3.3/gcc/Optimize-Options.html#Optimize%20O
ptions

> -O also turns on -fomit-frame-pointer on machines where doing so does not
interfere with debugging.
> ...
> -fomit-frame-pointer 
> Enabled at levels -O, -O2, -O3, -Os.

The last sentence should not be stated unconditionally.

> Note: pseudo instruction represents, in this particular context, an
abstract measurement of function's size.
> In no way, it represents a count of assembly instructions and as such its
exact meaning might change from
> one release to an another. 

Rife with grammatical errors. I suggest:

"Note: In this particular context, pseudo instruction represents an abstract
measurement of function size. In no way does it represent a count of
assembly instructions and as such its exact meaning might change from one
release to another."

> -fpeephole is enabled by default. -fpeephole2 enabled at levels -O2, -O3,
-Os. 
> -fbranch-probabilities 
> -fno-guess-branch-probability 
> Do not guess branch probabilities using a randomized model.

Nothing appears for -fbranch-probabilities here. It is documented in full
below.

> -fssa 
> ...
> -fssa-ccp
> ... 
> -fssa-dce

I recall hearing that -fssa is massively broken now. Should these even be
here?

> -fsched-spec-load-dangerous 
> Allow speculative motion of more load instructions. This only makes sense
when scheduling before register
> allocation, i.e. with -fschedule-insns or at -O2 or higher.

This doesn't say how speculatively moving "more" load instructions is
dangerous. Can it result in incorrect code being generated, or can it result
in slower code being generated? This should be clarified.

http://gcc.gnu.org/install/specific.html
The internal link to *-*-sysv* is broken. Here's the line which breaks it:

> <h3 class="heading"><a name="TOC53"></a><a
name="%23*-*-sysv*"></a>*-*-sysv*</h3>

http://gcc.gnu.org/develop.html#future
gcc 3.3 is not listed as released.

Stephan T. Lavavej
http://nuwen.net

Re: Documentation Buglets (-fssa)

[Andrew Pinski]

If you read the documentation fully, you will notice: `Users should not 
specify this option, since it is not yet ready for production use.'

I would agree that these should be removed from gcc fully.

Thanks,
Andrew Pinski

On Tuesday, May 20, 2003, at 16:00 US/Eastern, Stephan T. Lavavej wrote:

>> -fssa
>> ...
>> -fssa-ccp
>> ...
>> -fssa-dce
>
> I recall hearing that -fssa is massively broken now. Should these even 
> be
> here?

Re: Documentation Buglets (-fssa)

[Andrew Pinski]

On Tuesday, May 20, 2003, at 16:05 US/Eastern, Andrew Pinski wrote:

> If you read the documentation fully, you will notice: `Users should 
> not specify this option, since it is not yet ready for production > use.'
>
> I would agree that these should be removed from gcc fully.
            ^
          argue
Andrew Pinski

>
> Thanks,
> Andrew Pinski
>
> On Tuesday, May 20, 2003, at 16:00 US/Eastern, Stephan T. Lavavej 
> wrote:
>
>>> -fssa
>>> ...
>>> -fssa-ccp
>>> ...
>>> -fssa-dce
>>
>> I recall hearing that -fssa is massively broken now. Should these 
>> even be
>> here?
>
>
>

RE: Documentation Buglets (-fssa)

[Stephan T. Lavavej]

[Andrew Pinski]
> If you read the documentation fully, you will notice: `Users should
> not specify this option, since it is not yet ready for production 
> use.'

Yes, that's a prominent notice.  But, as you argue, -fssa is so broken, it
shouldn't even be mentioned.

Other "this might work, this might not" options are fine, if they have
warnings next to them, but if an option just plain doesn't _work_, it
shouldn't be there.

Stephan T. Lavavej
http://nuwen.net