for review: add a feww comments to runtime/*

[Fergus Henderson]

Zoltan or Tyson, could you please review this one for me?

--------------------

Estimated hours taken: 0.25

runtime/mercury_wrapper.h:
runtime/mercury_layout_util.h:
	Add some comments.

Index: runtime/mercury_layout_util.h
===================================================================
RCS file: /home/mercury1/repository/mercury/runtime/mercury_layout_util.h,v
retrieving revision 1.1
diff -u -r1.1 mercury_layout_util.h
--- mercury_layout_util.h	1998/10/16 06:18:52	1.1
+++ mercury_layout_util.h	1998/11/06 08:52:42
@@ -49,6 +49,11 @@
 			const MR_Stack_Layout_Vars *vars, Word *saved_regs,
 			Word *base_sp, Word *base_curfr);
 
+/*
+** Given a stack layout and the saved copy of the registers,
+** get the values of the live variables as a list of univs.
+** Any memory needed is allocated on the Mercury heap.
+*/
 extern	Word	MR_make_var_list(const MR_Stack_Layout_Label *layout,
 			Word *saved_regs);
 
@@ -98,6 +103,10 @@
 ** do not suceed if the variable's name indicates that the value is likely
 ** to be too big. This is a temporary measure only, until we get a better
 ** term printer.
+**
+** All of these functions may need to allocate memory (to hold the
+** type_infos that they return); any memory that they allocate will
+** be allocated on the Mercury heap.
 */
 
 extern	bool	MR_get_type_and_value(const MR_Stack_Layout_Var *var,
@@ -120,6 +129,8 @@
 /*
 ** MR_write_variable:
 **	Write a variable to stdout.
+**	This uses the fake_reg copies of the registers,
+**	and it may also clobber the real registers.
 */
 
 extern	void	MR_write_variable(Word type_info, Word value);
Index: runtime/mercury_wrapper.h
===================================================================
RCS file: /home/mercury1/repository/mercury/runtime/mercury_wrapper.h,v
retrieving revision 1.14
diff -u -r1.14 mercury_wrapper.h
--- mercury_wrapper.h	1998/10/16 06:19:14	1.14
+++ mercury_wrapper.h	1998/11/06 09:00:07
@@ -63,6 +63,7 @@
 /*
 ** Similarly, these are for the debugger interface; they're defined in
 ** browser/debugger_interface.m.
+** XXX These are obsolete; the browser can call the ML_ versions directly.
 */
 extern	void	(*MR_DI_output_current_vars)(Word, Word, Word);
 		/* output_current_vars/3 */
@@ -84,12 +85,14 @@
 /*
 ** ML_type_name() is defined in library/std_util.m and used in
 ** trace/mercury_trace_external.c.
+** XXX This is obsolete; the tracer can call the ML_ version directly.
 */
 
 extern	String	(*MR_type_name)(Word);
 		/* normally ML_type_name (type_name/1) */ 
 
 /*
+** XXX This is obsolete too.
 ** This variable has been replaced by MR_io_print_to_*_stream,
 ** but the installed mkinit executable may still generate references to it.
 ** We must therefore keep it until all obsolete mkinit executables have
@@ -98,6 +101,12 @@
 
 extern	Code	*MR_library_trace_browser;
 
+/*
+** MR_trace_func_ptr is set to either MR_trace_real (trace/mercury_trace.c), or
+** MR_trace_fake (runtime/mercury_trace_base.c),
+** depending on whether tracing was enabled when creating the _init.c
+** file.  It is called from MR_trace (runtime/mercury_trace_base.c).
+*/
 extern	Code    *(*MR_trace_func_ptr)(const MR_Stack_Layout_Label *,
 			MR_Trace_Port, Unsigned, Unsigned, const char *, int);
 

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "Binaries may die
WWW: <http://www.cs.mu.oz.au/~fjh>  |   but source code lives forever"
PGP: finger fjh at 128.250.37.3        |     -- leaked Microsoft memo.