RE: [boost] Re: Formal review of "Output Formatters" library beginstoday

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2004-09-12 14:11:12

David Abrahams wrote:
>"Reece Dunn" <msclrhd_at_[hidden]> writes:
>
> >>AFAICT the docs lack any sort of formalized reference guide, showing
> >>interface summaries, what headers to include, requirements, etc.  IMO
> >>it's unacceptable without that component.  Did I miss something?
> >
> > okay. IIUC, Doxygen will auto-generate these when provided
> > javadoc-like comments.
>
>You won't get Concept documentation from Doxygen unless you take care
>to actually write it ;-), and regardless I don't think this can be
>done as an afterthought.  I would be wary of taking this route unless
>your implementation is very simple.  It's important to present a
>coherent view of the *user interface* that doesn't expose
>implementation details.  For example, sometimes public inheritance
>from some helper class is neccessary as an implementation technique,
>and you don't want to expose it, but you need to expose the public
>members of that helper.  I don't think Doxygen can deal with that.

I suppose it depends what you are doing. If you are just 
inputting/outputting an object, then you don't need to be concerned with how 
things like boost::io::pairfmt() are implemented. However, you will need to 
know the object that pairfmt() returns if you want to save that type for use 
later, e.g.:

   // note: using new names:
   // renders the format: ( < a, b, c > | 5 )
   io::pair_fmt_t< const char *, io::container_fmt_t< const char * > >
      my_type_renderer = io::pair_fmt( io::container_fmt().format( "< ", " 
 >" )).format( " | " );
   std::pair< std::list< char >, int > data;

   std::cout << io::sequence( data, my_type_renderer ); // output: ( < a, b, 
c > | 5 )

NOTE: This is where typedecl/auto comes in useful, making the above example 
become:
   auto my_type_renderer =
      io::pair_fmt( io::container_fmt().format( "< ", " >" )).format( " | " 
);
   std::cout << io::sequence( data, my_type_renderer ); // output: ( < a, b, 
c > | 5 )

Likewise, you will not need to know how boost::io::formatter_t differs from 
boost::io::formatter in most cases. However, this becomes important when 
implementing your own format object (for example, adding tuple rendering 
support).

It's all about context.

Regards,
Reece

_________________________________________________________________
It's fast, it's easy and it's free. Get MSN Messenger today! 
http://www.msn.co.uk/messenger