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

[Julien Fischer]

On Tue, 31 Oct 2006, Peter Ross wrote:

> 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.

The coding standard doesn't mention switches, but the way  I suggest
is used throughtout the rest of the compiler; also it's easy to confuse
your formatting with if-then-elses.

>>>   %
>>>   % 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.

Again, this is what is used throughout most of the compiler.

Julien.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------