[m-rev.] for review: updates for opengl binding

[Fergus Henderson]

On 14-Aug-2003, Julien Fischer <juliensf at students.cs.mu.OZ.AU> wrote:
> 
> This diff is in preparation for another one that I have almost finished
> that implements a fairly large chunk of the functionality that is currently
> unimplemented.  With the exception of removing one small utility predicate
> and implementing it inline the changes here are mainly fixes/updates to
> syntax and formatting.
> 
> extras/graphics/mercury_opengl/mglu.m:
> extras/graphics/mercury_opengl/mogl.m:
>	[...]

> Index: mglu.m
...
> +:- pragma foreign_proc("C", look_at(Ex::in, Ey::in, Ez::in, Cx::in, Cy::in,
> +		Cz::in, Ux::in, Uy::in, Uz::in, IO0::di, IO::uo),
> +	[will_not_call_mercury, promise_pure], "
>  	gluLookAt((GLdouble) Ex, (GLdouble) Ey, (GLdouble) Ez,
>  		(GLdouble) Cx, (GLdouble) Cy, (GLdouble) Cz,
>  		(GLdouble) Ux, (GLdouble) Uy, (GLdouble) Uz);
>  	IO = IO0;
>  ").
> 
> -:- pragma c_code(perspective(Fovy::in, Asp::in, N::in, F::in,
> -		IO0::di, IO::uo), "
> +:- pragma foreign_proc("C", perspective(Fovy::in, Asp::in, N::in, F::in,
> +		IO0::di, IO::uo),
> +	[will_not_call_mercury, promise_pure], "
>  	gluPerspective((GLdouble) Fovy, (GLdouble) Asp,
>  		(GLdouble) N, (GLdouble) F);
>  	IO = IO0;
>  ").

Are you sure that the `will_not_call_mercury' declarations are correct?

> Index: mogl.m
...
>  %------------------------------------------------------------------------------%
> -%
> -% 2.5	GL Errors
> -%
> -%------------------------------------------------------------------------------%
> +% GL Errors.
> 

My preferred layout for "section heading" comments is

	%---------------------------------------------------------------------%
	%
	% Heading goes here
	%

	code goes here

(with the first line 79 characters long).  I've used this style quite
a bit in the Mercury compiler (especially the MLDS back-end).

This layout serves to visually distinguish "section heading" comments
from other kinds of comments, because they are "attached" to the section
division marker.

You have used this style:

	%---------------------------------------------------------------------%
	% Heading goes here

	code goes here

which is not bad, but I prefer the style I showed above, since I think
that makes the second headings a bit more prominent, and also for
consistency with the other code in the Mercury compiler.

So, I suggest that you change the section headings to use that style.
I also propose the following change to coding_standards.html.

Estimated hours taken: 0.25
Branches: main

compiler/notes/coding_standards.html:
	Add some documentation about the layout for section header comments.

Workspace: /home/ceres/fjh/mercury
Index: compiler/notes/coding_standards.html
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/notes/coding_standards.html,v
retrieving revision 1.7
diff -u -d -r1.7 coding_standards.html
--- compiler/notes/coding_standards.html	17 Jul 2002 06:23:57 -0000	1.7
+++ compiler/notes/coding_standards.html	17 Aug 2003 08:30:57 -0000
@@ -291,7 +291,51 @@
 
 %---------------------------------------------------------------------------%
 
+</pre>
+
+Ideally such sections should be identified by "section heading" comments
+identifying the contents of the section, optionally followed by a more
+detailed description.  These should be laid out like this:
+
+<pre>
+
+%---------------------------------------------------------------------------%
+%
+% Section title
+%
+
+% Detailed description of the contents of the section and/or
+% general comments about the contents of the section.
+% This part may go one for several lines.
+%
+% It can even contain several paragraphs.
+
+The actual code starts here.
+
+</pre>
+
+For example
+
+<pre>
+
+%---------------------------------------------------------------------------%
+%
+% Exception handling
+%
+
+% This section contains all the code that deals with throwing or catching
+% exceptions, including saving and restoring the virtual machine registers
+% if necessary.
+%
+% Note that we need to take care to ensure that this code is thread-safe!
+
+:- type foo ---> ...
+
+</pre>
+
 Double-dashed lines, i.e.
+
+<pre>
 
 %---------------------------------------------------------------------------%
 %---------------------------------------------------------------------------%
-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------