[m-rev.] for review: XML documentation of DU types pass

[Peter Ross]

On Tue, Oct 31, 2006 at 05:27:29PM +1100, Julien Fischer wrote:
> On Tue, 31 Oct 2006, Peter Ross wrote:
> >New File: compiler/xml_documentation.m
> >===================================================================
> >%-----------------------------------------------------------------------------%
> >% vim: ft=mercury ts=4 sw=4 et
> >%-----------------------------------------------------------------------------%
> >% Copyright (C) 2006 The University of Melbourne.
> >% This file may only be copied under the terms of the GNU General
> >% Public License - see the file COPYING in the Mercury distribution.
> >%-----------------------------------------------------------------------------%
> >%
> >% Module: xml_documentation.m
> >% Main authors: petdr.
> >%
> >% This module outputs an XML representation of a module,
> >% which can then be transformed by a stylesheet into some other
> >% documentation format.
> >%
> >%-----------------------------------------------------------------------------%
> >
> >:- module check_hlds.xml_documentation.
> >
> >:- interface.
> >
> >:- import_module hlds.
> >:- import_module hlds.hlds_module.
> >
> >:- import_module io.
> >
> >   %
> >   % Output a representation of the module in XML which can be used
> >   % to document the module.
> >   %
> >:- pred xml_documentation(module_info::in, io::di, io::uo) is det.
> >
> 
> ...
> 
> >%-----------------------------------------------------------------------------%
> >
> >xml_documentation(ModuleInfo, !IO) :-
> >   module_info_get_name(ModuleInfo, ModuleName),
> >   module_name_to_file_name(ModuleName, ".xml", no, FileName, !IO),
> >
> >   lookup_module_source_file(ModuleName, SrcFileName, !IO),
> >   io.open_input(SrcFileName, SrcResult, !IO),
> >   ( SrcResult = ok(SrcStream),
> >       build_comments(SrcStream, comments(map.init), Comments, !IO),
> >
> >       io.open_output(FileName, OpenResult, !IO),
> >       ( OpenResult = ok(Stream),
> >           ModuleInfoXmlDoc = module_info_xml_doc(Comments, ModuleInfo),
> >           write_xml_doc_to_stream(Stream, ModuleInfoXmlDoc, !IO)
> >       ; OpenResult = error(Err),
> >           unable_to_open_file(FileName, Err, !IO)
> >       )
> >   ; SrcResult = error(SrcErr),
> >       unable_to_open_file(SrcFileName, SrcErr, !IO)
> >   ).
> 
> The switches there should be formatted thus:
> 
> 
> 	(
> 	    SrcResult = ok(SrcStream),
> 	    build_comments(...
> 	;
>             SrcResult = error(...),
>             unable_to_open_file(...)
>         )
> 
I thought the coding standard was

	( X = cond_a,
		...
	; X = cond_b,
		...
	)

I personally find distinguishing between switches and disjunctions
is extremely useful, so I prefer to leave it the way it is.

> >   %
> >   % Return the string which represents the comment ending at the given 
> >   line.
> >   % The comment extends backwards until the the line above the given
> >   % line is not a comment only line.
> >   %
> >:- func get_comment_backwards(comments, int) = string.
> >
> >get_comment_backwards(Comments, Line) = Comment :-
> >   LineType = map.lookup(Comments ^ line_types, Line),
> >   ( LineType = comment(CurrentComment),
> >       CommentAbove = get_comment_backwards(Comments, Line - 1),
> >       Comment = CommentAbove ++ CurrentComment
> >   ; ( LineType = blank ; LineType = code ; LineType = code_and_comment(_) 
> >   ),
> >       Comment = ""
> >   ).
> 
> Reformat thus:
> 
> 	(
> 	    LineType = comment(CurrentComment),
>             CommentAbove = get_comment_backwards(Comments, Line - 1),
>             Comment = CommentAbove ++ CurrentComment
>         ;
>              ( LineType = blank
>              ; LineType = code
>              ; LineType = code_and_comment(_)
>              ),
>              Comment = ""
>         ).
> 

Similarly here, though I'm still trying to work out the best coding 
style for this type of switches.
--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------