From: Warren Young
Date: May 12 2005 9:54pm
Subject: Re: [PATCH] documentation and type_info fix
List-Archive: http://lists.mysql.com/plusplus/4399
Message-Id: <4283D086.6030105@etr-usa.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

Chris Frey wrote:

> Below is a patch that contains a couple suggested documentation changes,
> as well as an explanation of how the type system works in type_info.{h,cpp}.

I was able to rewrite this to be a lot clearer, I think.  Some of it was 
just straight rewriting, but I also moved a lot of it to more 
appropraite places, so only the salient bits remain in type_info.cpp. 
The "opinion" block is now a Wishlist item, and the explanation of 
type()'s inner workings became the seed of a Doxygen comment in type_info.h.

> Also in type_info.cpp, I changed part of the type lookup table, to match
> what I believe is intended: for every entry marked true, there should be
> a unique typeid() value.  Where there were duplicate typeid() entries,
> I left the last one set as true, as that is the one used when you look
> at the for loop in the mysql_ti_sql_type_info_lookup constructor.

I didn't study it deeply enough to know whether this is the right thing, 
so I've decided to trust that you know what you're doing here.  :)

> +	o Document the header layout, and which headers can be included alone,
> +	  and which can't.  Do this to optimize compile times, and allow
> +	  users to do the same.

Have you read Lakos's "Large Scale C++" book (probably got the title 
wrong)?  Are you proposing optimization of that sort?

The thing that bugs me about mysql++.h now is that it includes every 
header, most of them in straight alphabetical order.  This is certainly 
not the most efficient way.  There are two ways we can improve this:

- The obvious way is to stare at the Doxygen-generated include graphs 
long enough that we learn which #includes we can pare out of mysql++.h, 
and what reorderings would help, if any.  The problem with this is, it's 
brittle.  If we depend on one "leaf" header to #include a particular 
file and so don't include it from mysql++ any more, things will break if 
we find later that the leaf header doesn't actually need to #include the 
other one, so we remove it.

- A smarter way to go is to wrap each #include with the idempotency 
guard for that header, so it is never included from mysql++.h if a 
previous header already included it.  You can push this concept further 
by doing the same in the other headers, but just doing it at the top 
level will probably save a significant chunk of time, and there's no 
sense cluttering the code for small gains.  Unless I'm very wrong, the 
case we want to optimize for is end users building their own programs, 
not build time for MySQL++.  Putting mysql++.h in order should recover 
most of the wasted time for the end-user case.

> -/// stddef.h is not the same!)
> +/// stddef.h is not the same!)  This template mechanism also
> +/// makes the typeid() unique for each C++-equivalent of nullable
> +/// SQL field types, which are listed in type_info.cpp.

No objection.  Accepted.