Bug 26154 - [4.9/5/6 Regression] OpenMP extensions to the C language is not documented or doumented in the wrong spot
Summary: [4.9/5/6 Regression] OpenMP extensions to the C language is not documented or...
Status: REOPENED
Alias: None
Product: gcc
Classification: Unclassified
Component: c (show other bugs)
Version: 4.2.0
: P5 normal
Target Milestone: 4.9.4
Assignee: Not yet assigned to anyone
URL:
Keywords: documentation, openmp
Depends on:
Blocks:
 
Reported: 2006-02-07 13:44 UTC by Andrew Pinski
Modified: 2015-06-26 20:08 UTC (History)
2 users (show)

See Also:
Host:
Target:
Build:
Known to work:
Known to fail:
Last reconfirmed: 2006-04-11 03:00:09


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Andrew Pinski 2006-02-07 13:44:04 UTC
I noticed that the OpenMP extensions are not documented in the normal spot for extensions in the "Extensions to the C Language Family" in the manual.

This is wrong as they are extensions we support to the C standard.
Comment 1 Andrew Pinski 2006-02-07 13:44:50 UTC
This is a regression as the document is out of date now. 
Comment 2 Andrew Pinski 2006-04-11 03:00:09 UTC
It should be something like what XLC does at:
http://publib.boulder.ibm.com/infocenter/lnxpcomp/v8v101/topic/com.ibm.xlcpp8l.doc/compiler/ref/ruprpdir.htm#RUPRPDIR

Which is actually much better than what is even in the current GCC docs which is nothing even at the toplevel of extensions that GCC supports.
Comment 3 Mark Mitchell 2006-06-04 17:33:12 UTC
Yes, there should at least be a reference to online information about OpenMP in our manual.  At this is one of the major new features in 4.2, it should definitely be documented.  Diego, would you be able to put a pointer in the manual?
Comment 4 Diego Novillo 2006-06-04 18:03:07 UTC
(In reply to comment #3)

> Diego, would you be able to put a pointer in the manual?
> 
There are two references to the OpenMP API already.  One in the documentation of -fopenmp, the other with the documentation of the OpenMP gimple codes.  I don't think we need to duplicate API documentation when so much external documentation is available.
Comment 5 Mark Mitchell 2006-06-17 00:06:23 UTC
I agree that since there is a reference to the specification in -fopenmp it is not necessary to do more to document OpenMP in our manual.  (If we have extensions to OpenMP they should be documented, but that's another issue.)
Comment 6 Andrew Pinski 2006-06-17 00:20:16 UTC
(In reply to comment #5)
> I agree that since there is a reference to the specification in -fopenmp it is
> not necessary to do more to document OpenMP in our manual.  (If we have
> extensions to OpenMP they should be documented, but that's another issue.)

The current situtation with OpenMP is not the same as the rest of the documentation.  "Extensions to the C Language Family" is were extensions to the language STANDARD are documented, if they are not, then how would someone know what the extensions are?

Also -fopenmp is not an option to control "Code Generation Conventions" but instead the language which is accepted so it should be listed in "Options Controlling C Dialect" (and maybe "Options Controlling C++ Dialect.").
Comment 7 Andrew Pinski 2006-06-17 00:23:26 UTC
Also the pragmas should be listed under:
http://gcc.gnu.org/onlinedocs/gcc/Pragmas.html#Pragmas
Comment 8 Andrew Pinski 2006-06-17 00:26:29 UTC
Also we list extensions to C89 which are in C99 too so documenting this in "Extensions to the C Language Family" is the correct thing to do.

And nothing links directly to the spec, I have to go through another web page to get what each pargma does which is wrong, OUR document should be more complete instead of the current situation where it is half done.
Comment 9 Mark Mitchell 2006-06-17 00:28:26 UTC
Andrew --

Since you're unwilling to close this PR, I'll leave it open.  However, it's P5; I trust OpenMP users to be able to figure out how to find the OpenMP pragmas.

-- Mark
Comment 10 Andrew Pinski 2006-06-17 00:49:56 UTC
(In reply to comment #9)
> Andrew --
> 
> Since you're unwilling to close this PR, I'll leave it open.  However, it's P5;
> I trust OpenMP users to be able to figure out how to find the OpenMP pragmas.

Lets look at it a different way, how easy is it for a GCC user to see that GCC supports OpenMP.  It is hard because they have to look at the wrong section to find it does.  Yes the news section on the main web page says it exists but that is not an excuse for having not good documentation.  Let me also point out there are other extensions which are more documented than OpenMP even ones which are part of a standard like 
http://gcc.gnu.org/onlinedocs/gcc/Long-Long.html#Long-Long
http://gcc.gnu.org/onlinedocs/gcc/Hex-Floats.html#Hex-Floats
http://gcc.gnu.org/onlinedocs/gcc/Compound-Literals.html#Compound-Literals
http://gcc.gnu.org/onlinedocs/gcc/Mixed-Declarations.html#Mixed-Declarations
http://gcc.gnu.org/onlinedocs/gcc/Initializers.html#Initializers

Should I continue or can I say that OpenMP is just poorly documented and is inconsistent with the rest of GCC and is really an undocumented extension that can be removed still?

Even TLS is not documented the way OpenMP is:
http://gcc.gnu.org/onlinedocs/gcc/Thread_002dLocal.html#Thread_002dLocal
In fact it gives exact edits to the real standard.
Comment 11 Mark Mitchell 2007-05-14 22:28:00 UTC
Will not be fixed in 4.2.0; retargeting at 4.2.1.
Comment 12 Mark Mitchell 2007-10-09 19:22:21 UTC
Change target milestone to 4.2.3, as 4.2.2 has been released.
Comment 13 Joseph S. Myers 2008-02-01 16:52:52 UTC
4.2.3 is being released now, changing milestones of open bugs to 4.2.4.
Comment 14 Joseph S. Myers 2008-05-19 20:22:47 UTC
4.2.4 is being released, changing milestones to 4.2.5.
Comment 15 Joseph S. Myers 2008-07-04 19:48:46 UTC
Marking as regression again.
Comment 16 Joseph S. Myers 2009-03-31 19:29:09 UTC
Closing 4.2 branch.
Comment 17 Richard Biener 2009-08-04 12:27:32 UTC
GCC 4.3.4 is being released, adjusting target milestone.
Comment 18 Richard Biener 2010-05-22 18:10:57 UTC
GCC 4.3.5 is being released, adjusting target milestone.
Comment 19 Richard Biener 2011-06-27 12:12:37 UTC
4.3 branch is being closed, moving to 4.4.7 target.
Comment 20 Jakub Jelinek 2012-03-13 12:45:22 UTC
4.4 branch is being closed, moving to 4.5.4 target.
Comment 21 Jakub Jelinek 2013-04-12 15:15:55 UTC
GCC 4.6.4 has been released and the branch has been closed.
Comment 22 Richard Biener 2014-06-12 13:42:32 UTC
The 4.7 branch is being closed, moving target milestone to 4.8.4.
Comment 23 Jakub Jelinek 2014-12-19 13:32:20 UTC
GCC 4.8.4 has been released.
Comment 24 Richard Biener 2015-06-23 08:14:41 UTC
The gcc-4_8-branch is being closed, re-targeting regressions to 4.9.3.
Comment 25 Jakub Jelinek 2015-06-26 19:56:51 UTC
GCC 4.9.3 has been released.