On Wednesday, May 18, 2016 1:12:29 PM PDT Ian Romanick wrote: > 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." > + */
I've always done: /* ...something something OpenGL...: * * "Some quoted text from the specification. More quoted text. Yet * more quoted text. Still more quoted text. Multiple lines of quoted * text get indented so they line up with the text, not the open quote." */ I don't care for the four space indent (it just gives you less space), and I think it looks nicer if the opening quote is offset by 1 so that the actual quoted text lines up. It's just something I've always done. Having more consistency on the first line seems like a good idea, and I'm fine with what you proposed. > +</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: > Heh :) Nice.
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/mesa-dev
