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