From f4ad5ede58dd4e431d8fe8f93293934aa7094a78 Mon Sep 17 00:00:00 2001
From: Martin Smith <martin.smith@qt.io>
Date: Tue, 22 Nov 2016 10:31:12 +0100
Subject: doc: clangqdoc must always see GL typedefs

QT_NO_OPENGL must not be defined when running clangqdoc
because there are opengl elements that must be documented.
That means clang will see uses of GLxxx, which might not
be included on some platforms. For example, clang must
parse the declaration for class QOpenGLFramebufferObject,
which uses GLuint, GLenum, and GLbitfield, because there
is documentation to be published for that class in
qopenglframebufferobject.cpp.

This change uses Q_CLANG_QDOC to first undef the needed
GLxxx types and then provide suitable typedefs for them.
This technique is also used in qglshader.h.

This works for macOS, but is it the right way to solve the
problem?

This change also removes some \overload commands, because
they shouldn't be used on constructors. And some \fn commands
that are made unnecessary by upgrading to clang.

Change-Id: I4ac658e951b3f2011698005f0238d4dea85fc403
Reviewed-by: Martin Smith <martin.smith@qt.io>
---
 src/gui/opengl/qopenglframebufferobject.cpp | 13 ++++++-------
 src/gui/opengl/qopenglframebufferobject.h   | 12 +++++++++++-
 src/opengl/qglshaderprogram.h               | 11 +++++++++++
 3 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/src/gui/opengl/qopenglframebufferobject.cpp b/src/gui/opengl/qopenglframebufferobject.cpp
index 628475a90a..469f019a1c 100644
--- a/src/gui/opengl/qopenglframebufferobject.cpp
+++ b/src/gui/opengl/qopenglframebufferobject.cpp
@@ -816,7 +816,7 @@ static inline GLenum effectiveInternalFormat(GLenum internalFormat)
     return internalFormat;
 }
 
-/*! \fn QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, GLenum target)
+/*!
 
     Constructs an OpenGL framebuffer object and binds a 2D OpenGL texture
     to the buffer of the size \a size. The texture is bound to the
@@ -847,7 +847,7 @@ QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, GLenum tar
     d->init(this, size, NoAttachment, target, effectiveInternalFormat(0));
 }
 
-/*! \overload
+/*!
 
     Constructs an OpenGL framebuffer object and binds a 2D OpenGL texture
     to the buffer of the given \a width and \a height.
@@ -859,7 +859,7 @@ QOpenGLFramebufferObject::QOpenGLFramebufferObject(int width, int height, GLenum
 {
 }
 
-/*! \overload
+/*!
 
     Constructs an OpenGL framebuffer object of the given \a size based on the
     supplied \a format.
@@ -873,7 +873,7 @@ QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, const QOpe
             format.samples(), format.mipmap());
 }
 
-/*! \overload
+/*!
 
     Constructs an OpenGL framebuffer object of the given \a width and \a height
     based on the supplied \a format.
@@ -884,7 +884,7 @@ QOpenGLFramebufferObject::QOpenGLFramebufferObject(int width, int height, const
 {
 }
 
-/*! \overload
+/*!
 
     Constructs an OpenGL framebuffer object and binds a texture to the
     buffer of the given \a width and \a height.
@@ -905,7 +905,7 @@ QOpenGLFramebufferObject::QOpenGLFramebufferObject(int width, int height, Attach
     d->init(this, QSize(width, height), attachment, target, effectiveInternalFormat(internalFormat));
 }
 
-/*! \overload
+/*!
 
     Constructs an OpenGL framebuffer object and binds a texture to the
     buffer of the given \a size.
@@ -927,7 +927,6 @@ QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, Attachment
 }
 
 /*!
-    \fn QOpenGLFramebufferObject::~QOpenGLFramebufferObject()
 
     Destroys the framebuffer object and frees any allocated resources.
 */
diff --git a/src/gui/opengl/qopenglframebufferobject.h b/src/gui/opengl/qopenglframebufferobject.h
index b9e61e9ee4..161054d1bf 100644
--- a/src/gui/opengl/qopenglframebufferobject.h
+++ b/src/gui/opengl/qopenglframebufferobject.h
@@ -49,8 +49,18 @@
 
 #include <QtCore/qscopedpointer.h>
 
-QT_BEGIN_NAMESPACE
+#if defined(Q_CLANG_QDOC)
+#undef GLuint
+typedef unsigned int GLuint;
+#undef GLenum
+typedef unsigned int GLenum;
+#undef GL_TEXTURE_2D
+#define GL_TEXTURE_2D 0x0DE1
+#undef GLbitfield
+typedef unsigned int GLbitfield;
+#endif
 
+QT_BEGIN_NAMESPACE
 
 class QOpenGLFramebufferObjectPrivate;
 class QOpenGLFramebufferObjectFormat;
diff --git a/src/opengl/qglshaderprogram.h b/src/opengl/qglshaderprogram.h
index 3ce88197d2..dfdef44b54 100644
--- a/src/opengl/qglshaderprogram.h
+++ b/src/opengl/qglshaderprogram.h
@@ -46,6 +46,17 @@
 #include <QtGui/qvector4d.h>
 #include <QtGui/qmatrix4x4.h>
 
+#if defined(Q_CLANG_QDOC)
+#undef GLfloat
+typedef double GLfloat;
+#undef GLint
+typedef int GLint;
+#undef GLuint
+typedef unsigned int GLuint;
+#undef GLenum
+typedef unsigned int GLenum;
+#endif
+
 QT_BEGIN_NAMESPACE
 
 
-- 
cgit v1.2.3