Things that need to be done in PasDoc:
(Mostly done) Go through all comments and check them for validity and readability. There are a lot of comments that are outdated.
I think that most comments are correct now. The remaining things must be handled on a case-by-case basis. Everyone: feel free to submit bug reports (using our MailingList or sourceforge's bug tracker) about unclean and/or outdated pasdoc source documentation. – MichalisKamburelis
(Done, but not really correctly yet) Properties do not show read and write directives.
This is implemented now: full declaration of every property is shown, including read/write specifiers of this property. Actually too much is shown for now – even if read/write specifier specifies some private field or method, it is shown. But it shouldn't because names of private specifiers are, well, private, unless you requested them using --visible-members. This will be fixed later, for now you will have to live with too much private information shown in documentation. See also my mail of pasdoc-main MailingList "Full declaration of properties is now shown" on 2005-05-29. – MichalisKamburelis
tests/todo/ directory of pasdoc sources contains some ready test cases of known problems that should be fixed.
When using overloading, you have the same names for some routines within the same unit and the same class. This still has to be fixed: different versions of overloaded routine should have different anchors in documentation, and LinkTag should allow to specify to which overloaded version you're linking to (e.g. @link(Create(Integer, Integer)) or @link(Create(String)).
Some comments about it are also at the bottom of LatexOutput page.
Note that this requires first to have more intelligent parser, that understands procedure parameters names and types, see ToDoParser.
RichardBWinston submitted a patch OverloadPatch.patch that solves the first part of the problem in a simpler manner (without messing with the parser). I noone will manage to make the full fix, we will apply Richard's patch with small modifications to fix some issues (see "Patch for linking to overloaded methods in PasDoc" thread on pasdoc-main around 2006-09-23).
$if <boolean-condition> and $ifend directives are handled, but evaluating <boolean-condition> is not. PasDoc currently simply assumes that <boolean-condition> is true.
$elseif <boolean-condition> is not handled.
Global properties (implemented by FPC) are parsed correctly since 2006-11-25. But for now they are added by parser to U.Variables list. This should be fixed, either 1. we should have separate Properties list for each unit or 2. we should rename U.Variables to U.VariablesProperties and change corresponding strings for translators to say "Variables and global properties" instead of "Variables". Michalis prefers the 2nd option (as global properties behave like variables from the outside, just like normal properties behave like fields from the outside), but the problem is : the text "Variables and global properties" may confuse Delphi users not familiar with concept of "global properties".
Done:
(Done) properly parse duplicate names in different units or different classes, see DuplicateNames
(Done) RegressionTesting
(Done) Someone should take care of TPasDoc.SearchDescrFileTags and fix it, or remove it.
Removed in revision 1.12 of source/component/PasDoc_Base.pas. Reasons:
Implementation of TPasDoc.SearchDescrFileTags was hopelessly broken, and moving it to TDocGenerator.ExpandDescription is not so simple – you have to first scan for @descrfile, than you have to expand descriptions. Which means that we would have to make three passes over descriptions.
@descrfile was never present in the docs, and noone ever complained that it was disabled in PasDoc 0.9.0 and 0.10.0. So I guess that noone needs it.
In summary, existing code of SearchDescrFileTags was useless, so it's removed. – MichalisKamburelis