latest addition: docblock lexer/parser combo

my initial foray into the bug list at sourceforge for phpDocumentor has led to an unshakable conclusion: the docblock "parsing" currently used in phpDocumentor, well, sucks.

So, to solve problems such as this code breaking:

/**
* Watch the @include_once become a tag...
*
* Example:
* <code>
* @include_once 'oops_stupid_docblock_Parser.php';
* </code>
*/

I have started a hand-written lexer with an eye towards a phpJay-generated docblock parser. I had originally attempted a phpLex auto-generated lexer for docblocks, but it quickly became a 2000-line plus undebuggable mess of spaghetti. In addition, it simply couldn't do some things it needs to do, and so the docblock parser was far more complex than is healthy. With the current code in cvs (700-something lines), the lexer supports everything the current one does plus proper handling of things like {@internal}} and special tags <code></code>. More interesting, it supports nested simple lists (something humans intuitively can read) and has unit tests. There's work to be done (edge cases, and I just realized I forgot to implement <ul><ol><li>) but mostly we're fast on the way to an improved docblock parsing system, the first in a series of minor refactors that will add up to a major improvement in code, performance, and memory usage of phpDocumentor.