#43 PasDoc2 suggestions
After inspection of the PasDoc code, this is what I want to change:
1) improve C style comment handling
2) settings for missing or default markers
3) introduce explicit block comments
4) use specific single-char comment markers
5) shrink parser code size (to ~50%)
6) simplify translation
[1-4] reflect my personal needs, for adding documentation to existing (third party...) code. The implementation took me a few hours, but broke the standard behaviour of PasDoc. Then I felt a need to apply more changes, in order to make the whole project easier to maintain. This is why I come back, with the offer to participate in the PasDoc project, for some more work on it.
[5] is the central point: some more or less extensive changes will allow to remove about half of the parser code.
[5a] Most important is a move from a token class to an token record, which eliminates the need for try-finally blocks. Consumption of the tokens doesn't require any explicit code, the old token record simply is overwritten with the new data on every fetch of the next token.
[5b] A common TokenType enum, including keywords and symbols, will also simplify the parser code.
[5c] Next comes centralized handling of declaration and description strings, which eliminates the need for explicit concatenation of the whitespace and comment token data strings. The ItemsForNextBackComment and similar lists are replaced by new member lists, whose last entry represents the "current" item, which receives the item name(s), declarations and raw descriptions from the token getter.
[5d] A declaration list is added to all "scoped" items, with members, like units and classes. This list collects and owns all member declarations, with one element for any number of identifiers in one declaration. The old member lists are replaced by something like a StringPairList, whose strings reflect the name and raw description of an individual item, and the (possibly shared) object represents its declaration.
[5e] A scope stack simplifies the placement of new declarations, which always go into the currently open (top level) scope item.
[6] is an option, which will make it easier to add languages, find all the strings without a translation, and at the same time reduces memory requirements.
Currently I'm morphing the parser, to the above model, and need some testers and more support. I'd be glad to present my recent work e.g. in an new branch. But if nobody else is interested in it, I'll open up a new project of my own.
DoDi
Logged In: YES
user_id=987895
Originator: NO
As for [1-4], I would have to see what it actually does to judge. Please note that breaking compatibility is bad, and you should avoid it.
[5a] please do not. TToken stays as a class. It's true, this forces us to write more try-finally blocks, but classes are simply much more comfortable to operate in other regards. [5b] is Ok if it really simplifies a lot of code. For the rest of [5] -- again, I would have to actually see how and what exactly they do. Some of them sound good, if they actually simplify the implementation.
[6] this is planned to be solved by gettext. See how e.g. Lazarus does it.
One very important note: please do not send one patch with this all implemented at once, as then it's really hard to discuss and apply it. With so large changes, there will inevitably be some discussion.
Do you mean you want to become a member and work in a branch of pasdoc SVN? It's not a problem, send some preliminary patches or just a link to new code to the mailing list. If it looks Ok, then you'll be more than welcome to become a member and continue work within a branch.
Logged In: YES
user_id=707179
Originator: NO
I know, both subjects are very complex and need a lot of time and maybe the popularity can be non-existing. But it would be great :)
There is a JEDI project that has such a parser, that could do the work. Unfortunately I cannot tell more about it, since I know it hardly. And - as far as I know - the project is sleeping.