From: Ian Romanick <ian.d.roman...@intel.com>
v2: Remove extra "ES" from "GLSL ES ES". Noticed by Chris Forbes.
v3: Many updates based on (very old) feedback from Paul Berry and (more
recent) observation of what is most commonly done in the code base.
Signed-off-by: Ian Romanick <ian.d.roman...@intel.com>
Cc: Brian Paul <bri...@vmware.com>
---
docs/devinfo.html | 84 +++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 76 insertions(+), 8 deletions(-)
diff --git a/docs/devinfo.html b/docs/devinfo.html
index 8ebf80f..fc0001b 100644
--- a/docs/devinfo.html
+++ b/docs/devinfo.html
@@ -81,18 +81,86 @@ Multi-line comment:
* never used before, allocate a buffer object now.
*/
</pre>
-We try to quote the OpenGL specification where prudent:
+
+<p id="spec_quotes">
+It is often useful to quote sections from relevant specifications near code
+that implements part of the spec. In order to make it easier to find such
+quotations in the code (via grep and friends) and to find the quoted text in
+the specifications, use one of the following formats.
+</p>
+
+<p>
+Text quoted from the core OpenGL, OpenGL ES, GLSL, GLSL ES, GLX, or EGL
+specifications should be formatted as:
+</p>
+
+<pre>
+ /* Section ##.##.## (Section Name) of the OpenGL #.# spec says:
+ *
+ * "Some quoted text from the specificiation. More quoted text. Yet
+ * more quoted text."
+ */
+</pre>
+
+<p>
+Quotations from the GLSL or GLSL ES specifications should be attributed to
+"GLSL" or "GLSL ES", respectively (i.e., <em>not</em> the full name "OpenGL
+Shading Language" or "OpenGL ES Shading Language"). Note: There are a total
+of 5 spaces between the <tt>*</tt> and the <tt>"</tt> starting the quotation.
+</p>
+
+<p>
+The practice used to be to include the page number in the quotation. This
+posed several problems. First, the page number printed on the page and the
+page number in the specification PDF never match. For this reason both page
+numbers were quoted, and it was very annoying. Second, from version to
+version of the specification the page number could change quite
+significantly. This made it difficult to detect when the specification had
+changed. Differences between the Core Profile and Compatibility Profile
+specifications made this issue even worse.
+</p>
+
+<p>
+Spec quotations from OpenGL 3.2 or later should also include the Profile being
+quoted. For example, a quote from the Core Profile spec would read:
+</p>
+
+<pre>
+ /* Section ##.##.## (Section Name) of the OpenGL #.# (Core Profile) spec
+ * says:
+ *
+ * "Some quoted text from the specificiation. More quoted text. Yet
+ * more quoted text."
+ */
+</pre>
+
+<p>
+Text quoted from an extension specifications:
+</p>
+
+<pre>
+ /* The EXT_foo_bar spec says:
+ *
+ * "Some quoted text from the specificiation"
+ */
+</pre>
+
+<p>
+Since extension specifications are generally small, it is usually easy enough
+to find the quoted text without including a section number. One exception to
+that is the issues section. Even careful spec readers may miss things in the
+issues section, so it is helpful to draw attention to quotations from the
+issues.
+</p>
+
<pre>
- /* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
+ /* The EXT_foo_bar spec says:
*
- * "An INVALID_OPERATION error is generated for any of the following
- * conditions:
+ * "Issues:
*
- * * <length> is zero."
+ * (#) Got an issue?
*
- * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec
- * (30.10.2014) also says this, so it's no longer allowed for desktop GL,
- * either.
+ * RESOLVED: Have a tissue."
*/
</pre>
Function comment example:
--
2.5.5
_______________________________________________
mesa-dev mailing list
mesa-dev@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/mesa-dev
