Re: [Pasdoc-main] PasDoc 0.12.0 release next week, and decisions for PasDoc2 branch

[Michalis K. <mic...@gm...>]

Hans-Peter Diettrich wrote:
> Michalis Kamburelis schrieb:
> 
>> Quick test showed that the version from the PasDoc2 branch still fails
>> on a lot of testcases. This was mentioned e.g. here
>> https://sourceforge.net/mailarchive/message.php?msg_id=4883125E.2050809%40gmail.com
>> , and many issues are still not fixed.
> 
> Some "bugs" can not be fixed without a deep change to the PasDoc data 
> structures, so that e.g. nested declaration sections (in class 
> declarations) can be handled at all. I've been waiting for according 
> specifications or actions from your part, but nothing happened. So I 
> only could do some more "cosmetic" changes to the existing model and 
> generators, as far as I could figure out how the existing model was 
> intended to work.

My objections were about bugs in your PasDoc2 branch code, bugs that
didn't exist in original trunk code. I honestly don't know what
"specifications" or "actions" on my part you were waiting for. These
bugs didn't exist in the trunk code in the first place. Some of them are
range check errors when parsing valid code, and I can't imagine how any
"specification" or (more) architectural changes of pasdoc would help
here. Bugs need to be fixed, and when you introduce them --- it's
usually your job to fix them.

I understand that you didn't have time to do it. It's Ok. Neither did I.
Just don't blame it on waiting for some action on my part, something
that I had no idea about.

> Another observation was the source code pollution, caused by 
> documentation comments in e.g. class declarations. Such comments IMO 
> should be moved into the implementation part, what would require to 
> parse that part as well. That's why I concentrated on external 
> description files, that are and remain applicable even after changes to 
> the source code structure, and do not rely so much on extensions to the 
> various language versions (Delphi, FPC...). 

This is an old question, whether documentation should go to the
interface, and thus "pollute" the interface. In my opinion yes, because
this makes interface more useful. But I agree that it's a matter of
taste, I wrote my opinion about this on
http://pasdoc.sipsolutions.net/MichalisKamburelis#Should_documentation_be_placed_inside_units_interface.2C_or_in_separate_files_.3F

>Then parsers can be 
> implemented quite independently from the internal PasDoc model, e.g. can 
> be borrowed from FPC or Lazarus. Their output would provide an 
> declaration tree, or a flat list of qualified identifiers, that can be 
> matched with any (applicable!) PasDoc tree model, and/or with external 
> topic files. The existing PasDoc model was inapplicable, up to the time 
> when I left the project.

So you have to parse the code anyway, in any approach (comments in the
interface, or implementation, or external files). The reasons for using
our own parser were, and still are, that

1. At least fcl-passrc still doesn't offer all the features. There were
many improvements recently, but still e.g. FPC macros are not supported.
Not to mention that latest Delphi's features (which are the main lack of
pasdoc according to bugreports) aren't probably implemented there
either, as FPC doesn't handle many of them.

2. Noone implemented it. Using fcl-passrc, or any other open parser (I
remember at least JEDI parser mentioned in the past) is always a welcome
option. But you have to prove that it works (on testsuite, on
autodoc). Right now, since we know that fcl-passrc is not perfect,
implementing it as an alternative parser (that can be used instead of
the current one, activated e.g. by command-line option) would probably
be the right way to go.

Whether PasDoc_Items model should be upgraded for new Delphi features is
IMO orthogonal to the fact that parser should be upgraded / replaced.
I'm all after upgrading the PasDoc_Items model, as long as it's done in
a way that can be applied and doesn't break stuff that is already
working correctly.

> I just received a note from another contributor, who wanted to provide 
> Unicode-related improvements. He seems to be blocked by your many recent 
> changes to the trunk. Can you provide a roadmap, about the intended 
> changes, and how other activities could fit into the revised project?

Looks like I also received a mail from him, looks like he's talking to
us in parallel. And his work is completely applied to trunk now, see my
mail "Support for Delphi Unicode compilers" a second ago.

Although I didn't hear from him about being blocked by my changes. And
it would be strange, as we had 2 years of inactivity (except applying
small patches and translations), followed by changes mostly to
pasdoc_gui in recent days. I honestly can't see how I could do *less*
work, so I really can't imagine how I'm blocking someone. The pasdoc
architecture stayed virtually untouched for 2 years, plenty of time if
someone wants to provide patches. And many people did, and I tried to
apply them quickly --- as long as I could see that the change is good
and code compiles and works.

> 
> We differ in many ideas, how things should be made working. I've 
> implemented and tested my approach(es) for feasability, but only on the 
> small scale, i.e. the implementation may not work yet in certain cases. 

Your implementation doesn't work. And instead of fixing the bugs, you
only respond with emails talking how "the model is inapplicable" or
such. I don't know how you tested your code, but it *doesn't work*.
Autodoc fails, testsuite fails. These both tests were available to you
in pasdoc SVN, and mentioned to you many times. See previous mails for
details.

> But unless decisions are made, how things *shall* work in a future 
> PasDoc version, I consider even minor bugfixes to the existing code 
> nothing but a waste of time.

You seem to demand from me some big decision, where I don't see a need
to make one. The "plan" is to keep PasDoc working, parsing Pascal
sources with latest Delphi and FPC features, and make output useful.
Whoa, that was deep.

Everything may be changed (alternative parser, PasDoc_Items tree, etc.)
when it's needed. Just do it as gradually as possible, and don't
introduce bugs (or at least fix them afterwards).

> 
> Does there exist any documentation of the (current/intended) tree 
> structure, in general and in implementation details? I definitely 
> deserve some concrete material, that could convince me to resume working 
> on PasDoc.
> 

The autodoc http://pasdoc.sipsolutions.net/PasDocAutoDoc is our
documentation.

Michalis