Re: [boost] Adding a generic list manipulator

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2003-04-16 09:24:13

Rozental, Gennadiy wrote:

>1. Unfortunately for you and me ECMAScript is banned on boost doc pages.

The use of JavaScript in the HTML file is the result of support for 
switching between main sections and a top-level table of contents. That 
feature is not used in this document, so the related code can be removed.

This will not be an issue once I switch to a boost-style XSLT. I was just 
using one I already had to speed up the document generation process.

>2. You may wanna add copyright statements

I will asap. I just wanted to get feedback on the basic document - layout, 
style, examples, etc - so I could improve the explanations, examples and so 
forth while I was writing it.

>3. Highlighting colors you are using too glaring IMO.

Terje wrote:

>Finally, I agree with Gennadiy that the colours used in the documentation
>tends to make it hard to read, when one is used to black on white, and it's
>white on black. I suggest using black on white, like the other Boost
>documentation.

That is why the source is in XML. There is no colouring information in the 
XML file, that is all done by the XSLT file. You will notice that the print 
version has the black on white form. IMHO, I find that I prefer white on 
black, but that is what the XSLT/CSS is for!

Just edit the default.css file to your colour preferences and voila! (This 
will not work for the syntax highlighting, though, because that XSLT 
technology is in its early stages).

NOTE: I am thinking about writing an XSLT file that will generate 
boost-style documentation.

>Regarding the use of names starting with double underscore:

I shall look at changing this. Thanks.

>" __cdecl" - This is Microsoft-specific, so it may be a good idea to remove
>(it can always be set in the project settings, instead).

The MS compiler seems to want this on the main function. It generates a 
warning if you don't. I constructed the test program from a console 
skeleton, and that had the

   int __cdecl main(){ ... }

construct. I shall remove this in the next posting along with updates based 
on the feedback.

>Some of the headers have very odd formatting, such as array_output.hpp:
>[snip]
>Is this intentional?

I am in the habit of indenting variables to 40 spaces, methods to 50, 
operators to 35, typedefs to 60, and constructors/deconstructors to 30. 
Variations on that are an error on my part.

Rationale: If I have a complex class (e.g. formatlist_t) it is easy to see, 
for example, all the variables I have by scanning vertically down at 40 
spaces.

The

   namespace boost { namespace io
   {
      // ...
   }}

layout is a condensed form of

   namespace boost
   {
      namespace io
      {
         // ...
      }
   }

to cut down the indentation level, especially with things like 
boost::io::detail!

Also, because the

   inline OutputStream & operator()
                         (
                            OutputStream & os,
                            const T * array
                         ) const;

is too big to fit neatly on one line, I align the '(' and ')' with 
'operator()' because they are associated with that decleration.

I also try wherever possible to keep the declerations and implementations 
seperate. Not all of the methods are like that (see 
format_objects/container_output.hpp for an example), but this is because of 
one of two reasons:

[1] it is a template member of a template class, so older/non-conformant 
compilers will not accept the seperated versions.
NOTE: Is this fixed in MSVC 7.1??

[2] it is a relatively new piece of code, so I was focusing on getting an 
implemetnation available as fast as possible.

I have more rules that I apply when coding, but I will not list them here.

>Some headers, such as list_output.hpp, are not stand-alone. Including it
>gives several errors about undefined names.

This is my mistake. I designed the library so you would include the base 
file formatlist.hpp, that icludes everything else. I shall look at modifying 
it so that the files can be individually included.

>Some names don't conform to Boost's coding standard, such as
>"spaceAroundList()" (instead of "space_around_list()").

I shall modify the names to conform with Boost's coding standards, as they 
are part of the interface.

>This is meant as constructive feedback, to help you improve it. :)

I appreciate the feedback.

-----

I have not implemented any of the suggestions above at this time, but I have 
increased the portability of the library. I have tested it on the following:
*  MSVC 7.0
*  Borland C++Compiler 5.5.1
*  GCC 3.0.3 (i686-pc-cygwin)

The library is known to have problems with GCC 2.95.3-5.

Other compiler/library configurations have not been tested.

TO DO:
*  work on the documentation
*  clean up the code
*  work on the examples/test files
*  extensions???

-rhd-

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