pasdoc-main

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Hans-Peter D. <DrD...@ao...>]

Michalis Kamburelis schrieb:

> DoDi: you can upload your own compiled pasdoc.exe to our webspace. Open
> SSH connection to
> ssh://username,pa...@we.../home/groups/p/pa/pasdoc/htdocs/snapshots,
> create directory named 2009-01-17 there, and basically upload whatever
> you like there, like pasdoc.exe testing binary. This is the place for
> sharing testing pasdoc binaries, archives of whatever pasdoc versions
> (PasDoc2 or current trunk), basically just anything related to pasdoc.
> As a pasdoc developer, you should have full access there.
> 
> See SourceForge docs for other methods to upload files to webspace.

The docs have not been very helpful :-(

> Alternatively, just send me through email whatever you want to place
> there, and I'll upload it there for you :)

The zipped exe was rejected (illegal attachment). Should I try 7zip instead?

DoDi

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

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

Hans-Peter Diettrich wrote:
> 
> I'm not familiar with the current distribution policies and procedures, 
> of SourcForge and FreePascal. Perhaps Michalis can do that?

I can't compile for Windows right now (I don't have any Windows
available at home, and didn't set up crosscompiling...). So I can only
prepare Linux / Mac OS X binaries right now.

DoDi: you can upload your own compiled pasdoc.exe to our webspace. Open
SSH connection to
ssh://username,pa...@we.../home/groups/p/pa/pasdoc/htdocs/snapshots,
create directory named 2009-01-17 there, and basically upload whatever
you like there, like pasdoc.exe testing binary. This is the place for
sharing testing pasdoc binaries, archives of whatever pasdoc versions
(PasDoc2 or current trunk), basically just anything related to pasdoc.
As a pasdoc developer, you should have full access there.

See SourceForge docs for other methods to upload files to webspace.

Alternatively, just send me through email whatever you want to place
there, and I'll upload it there for you :)

Thomas (or anyone else, for that matter) can then download it by going
to appropriate http://pasdoc.sourceforge.net/snapshots/ subdirectory.

Michalis

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Hans-Peter D. <DrD...@ao...>]

Thomas Hummes schrieb:

>>>>> type TMyList = TObjectList<TStringList>;
>>>>>
>>>>> This creates a generic descendant of TObjectList containing
>>>>> TStringLists.
>>>>>         
>>
>> Is this really correct?
>> I've added this construct to the test unit. 
>>   
> Not really, I forgot the class(...).    :-[
> Correct would be
>  type TMyList = class(TObjectList<TStringList>);

Okay, I'll remove that part from the parser. Not a big deal :-)


>> I've updated the parser, and added your unit to the test directory 
>> (everything only in the PasDoc2 branch).
>>   
> Since I cannot compile PasDoc2 or PasDoc with Delphi 2009 (Problems with 
> Unicode-String), is there any directory
> in the SVN with compiled versions (pasdoc.exe)?

I'm not familiar with the current distribution policies and procedures, 
of SourcForge and FreePascal. Perhaps Michalis can do that?

Why don't you use FPC/Lazarus for building the executables?

Doesn't D2009 come together with an older Delphi version? AFAIR D1 was 
shipped together with D2 and D3, and D7 with D8.



> Some time ago, I started to develop myself a gui because the pasdoc-gui 
> was not able to produce several output formats and call HTML Help 
> Workshop afterwards, automatically. It will definetly not compile with 
> Lazarus, but if you are interested, I can review and comment it and you 
> could put it in the SVN as well.

Okay, please send me the commented version. Compatible with D7, if 
possible, because I don't have access to D2009.

DoDi

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Thomas H. <Tho...@gm...>]

Hans-Peter Diettrich schrieb:
> Thomas Hummes schrieb:
>
>   
>>>> This is not really correct. To use e.g. a generic TObjectList you
>>>> need to include the unit "Generics.Collections" and may then write
>>>> something like:
>>>>
>>>> type TMyList = TObjectList<TStringList>;
>>>>
>>>> This creates a generic descendant of TObjectList containing
>>>> TStringLists.
>>>>         
>
> Is this really correct?
> I've added this construct to the test unit. 
>   
Not really, I forgot the class(...).    :-[
Correct would be
 type TMyList = class(TObjectList<TStringList>);
>
>   
>> I attached a test unit with all basic samples needed to use existing 
>> generics.
>>     
>
> Thanks :-)
>
> I've updated the parser, and added your unit to the test directory 
> (everything only in the PasDoc2 branch).
>   
Since I cannot compile PasDoc2 or PasDoc with Delphi 2009 (Problems with 
Unicode-String), is there any directory
in the SVN with compiled versions (pasdoc.exe)?
> The <...> part is added to the declaration, but not to the ancestor list.
>
>
> BTW, I had some hardware problems (rapidly extending disk failures), and 
> have moved my PasDoc VM to another drive. This problem prevented me from 
> finishing a distribution of PasDoc2 for Christmas. Today SVN found some 
> conflicts, which I hope to have fixed now.
>
> I'm also familiarizing with Lazarus, perhaps I can port the D7 GUI to 
> Lazarus in the next time (months).
>
> DoDi
>   
Some time ago, I started to develop myself a gui because the pasdoc-gui 
was not able to produce several output formats and call HTML Help 
Workshop afterwards, automatically. It will definetly not compile with 
Lazarus, but if you are interested, I can review and comment it and you 
could put it in the SVN as well.
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by:
> SourcForge Community
> SourceForge wants to tell your story.
> http://p.sf.net/sfu/sf-spreadtheword
> _______________________________________________
> Pasdoc-main mailing list
> Pas...@li...
> https://lists.sourceforge.net/lists/listinfo/pasdoc-main
>
>   

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Hans-Peter D. <DrD...@ao...>]

Thomas Hummes schrieb:

>>> This is not really correct. To use e.g. a generic TObjectList you
>>> need to include the unit "Generics.Collections" and may then write
>>> something like:
>>>
>>> type TMyList = TObjectList<TStringList>;
>>>
>>> This creates a generic descendant of TObjectList containing
>>> TStringLists.

Is this really correct?
I've added this construct to the test unit.


> I attached a test unit with all basic samples needed to use existing 
> generics.

Thanks :-)

I've updated the parser, and added your unit to the test directory 
(everything only in the PasDoc2 branch).

The <...> part is added to the declaration, but not to the ancestor list.


BTW, I had some hardware problems (rapidly extending disk failures), and 
have moved my PasDoc VM to another drive. This problem prevented me from 
finishing a distribution of PasDoc2 for Christmas. Today SVN found some 
conflicts, which I hope to have fixed now.

I'm also familiarizing with Lazarus, perhaps I can port the D7 GUI to 
Lazarus in the next time (months).

DoDi

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Thomas H. <Tho...@gm...>]

unit GenericExample;

interface

{ Unit to include for Generics }
uses Generics.Collections;

type
 { A simple Test-Object }
 TMyObject = class(TObject);

 TMyGenericList = class(TObjectList<TMyObject>)
  public
   // To Something here
  end;

 { Sample for a generic with more than one type. TPair is a Key-Value-Relation }
 TAnotherGenericType = class(TDictionary<TObject,TObject>);

 { All standard Generics:
   TArray = class
   TEnumerator<T> = class abstract
   TEnumerable<T> = class abstract
   TList<T> = class(TEnumerable<T>)
   TQueue<T> = class(TEnumerable<T>)
   TStack<T> = class(TEnumerable<T>)
   TPair<TKey,TValue> = record
   TDictionary<TKey,TValue> = class(TEnumerable<TPair<TKey,TValue>>)
   TObjectList<T: class> = class(TList<T>)
   TObjectQueue<T: class> = class(TQueue<T>)
   TObjectStack<T: class> = class(TStack<T>)
   TObjectDictionary<TKey,TValue> = class(TDictionary<TKey,TValue>)

   The placeholder <T> is only necessary when designing own generics. Specializing existing
   types replace <T> with <DesiredType>.

   Quick and usable solution would be: Let the class name of TMyGenericList be
   "TObjectList<TMyObject>" and just reference to TObjectList.
  }




implementation

uses Classes;

procedure SampleProc();
var
 TestList: TMyGenericList;
 TestList2: TObjectList<TStringList>; // also allowed for vars
begin
 TestList:=TMyGenericList.Create();
 TestList2:=TObjectList<TStringList>.Create();

 TestList.Free;
 TestList2.Free;
end;

end.

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Hans-Peter D. <DrD...@ao...>]

Thomas Hummes schrieb:

>> More extensions to the parser are required, new keywords like
>> "generic" and the related syntax, etc.
> 
> This is not really correct. To use e.g. a generic TObjectList you
> need to include the unit "Generics.Collections" and may then write
> something like:
> 
> type TMyList = TObjectList<TStringList>;
> 
> This creates a generic descendant of TObjectList containing
> TStringLists.

I.e. TObjectList<TStringList> sould be treated as something like a 
qualified typename?

If so, of what type class? Should it become a CIO, or some unspecific 
type like "integer"? A CIO with ancestor TObjectList IMO were the 
closest internal representation. From the viewpoint of a user: where 
should the typename occur in the generated documentation, as TYPE or as 
CIO-TYPE?

> Michalis "dirty" solution isy at least be a solution
> for the most used new feature of Delphi 2009.

Okay, I'll look into that. Can somebody provide an test unit?

> Of course for other new
> things like anonymous methods, writing own generics (which needs a
> type called <T> as Placeholder for the later used class), a correct
> complete grammar ist needed - which I cannot provide, since I don't
> really understand how PasDoc works and how changes like these need to
> be planned and implemented.

A grammar snippet would be very helpful. Can such names only occur in 
type definitions, i.e.:
   TypeID ::= ident [ "<" ident ">" ] .
   TypeDef ::= "type" ident "=" TypeID ";"
or also in variable definitions
   Declaration ::= "var" ident [...] ":" TypeID ";"

DoDi

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Thomas H. <tho...@gm...>]

-------- Original-Nachricht --------
> Datum: Thu, 15 Jan 2009 23:02:11 +0100
> Von: Hans-Peter Diettrich <DrD...@ao...>
> An: "Discussion, announcements, 	questions concerning pasdoc" <pas...@li...>
> Betreff: Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

> Michalis Kamburelis schrieb:
> 
> >> D2009 has more extensions to the grammar (local types...), for which a 
> >> grammar is required. PasDoc2 already has provisions to handle such 
> >> extensions, but any implementation deserves a grammar in the first 
> >> place, followed by a decision about the representation of the added 
> >> elements.
> >>
> >> DoDi
> >>
> > 
> > Indeed, contributions to Delphi 2009 syntax are welcome. I don't own any
> > Delphi now, so I can only offer applying the patch if someone will
> > submit one :)
> 
> We also can wait for the FPC parser/grammar, compatible with D2009.
> 
> I'd prefer to use the FPC parser immediately, as seems to be done in 
> FPDoc, but I'm not sure where that parser resides, and how it can be 
> used outside of FPC.
> 
> > For starters, just to make it basically parsed, I would even accept a
> > patch that parses it dumbly and places class name =
> > "TObjectList<MyClass>". That is, the simplest approach to just treat
> > whole "TObjectList<MyClass>" as a single identifier, without linking it
> > to the generic TObjectList. Of course, a better patch would be most
> > welcome ---I'm just saying that any crude solution will be accepted in
> > the meantime (as long as it doesn't break any normal parsing of course).
> 
> More extensions to the parser are required, new keywords like "generic" 
> and the related syntax, etc.

This is not really correct. To use e.g. a generic TObjectList you need to include the unit "Generics.Collections" and may then write something like:

type
 TMyList = TObjectList<TStringList>;

This creates a generic descendant of TObjectList containing TStringLists. Michalis "dirty" solution isy at least be a solution for the most used new feature of Delphi 2009. Of course for other new things like anonymous methods, writing own generics (which needs a type called <T> as Placeholder for the later used class), a correct complete grammar ist needed - which I cannot provide, since I don't really understand how PasDoc works and how changes like these need to be planned and implemented. 

> 
> > DoDi: remember that bug submitters do not have to be subscribed to
> > mailing list, so it's best to answer by adding a comment to the bug. (In
> > this case Thomas is subscribed, just mentioning...).
> 
> Thanks for the hint :-)
> 
> DoDi
> 
> 
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by:
> SourcForge Community
> SourceForge wants to tell your story.
> http://p.sf.net/sfu/sf-spreadtheword
> _______________________________________________
> Pasdoc-main mailing list
> Pas...@li...
> https://lists.sourceforge.net/lists/listinfo/pasdoc-main

-- 
Psssst! Schon vom neuen GMX MultiMessenger gehört? Der kann`s mit allen: http://www.gmx.net/de/go/multimessenger

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Hans-Peter D. <DrD...@ao...>]

Michalis Kamburelis schrieb:

>> D2009 has more extensions to the grammar (local types...), for which a 
>> grammar is required. PasDoc2 already has provisions to handle such 
>> extensions, but any implementation deserves a grammar in the first 
>> place, followed by a decision about the representation of the added 
>> elements.
>>
>> DoDi
>>
> 
> Indeed, contributions to Delphi 2009 syntax are welcome. I don't own any
> Delphi now, so I can only offer applying the patch if someone will
> submit one :)

We also can wait for the FPC parser/grammar, compatible with D2009.

I'd prefer to use the FPC parser immediately, as seems to be done in 
FPDoc, but I'm not sure where that parser resides, and how it can be 
used outside of FPC.

> For starters, just to make it basically parsed, I would even accept a
> patch that parses it dumbly and places class name =
> "TObjectList<MyClass>". That is, the simplest approach to just treat
> whole "TObjectList<MyClass>" as a single identifier, without linking it
> to the generic TObjectList. Of course, a better patch would be most
> welcome ---I'm just saying that any crude solution will be accepted in
> the meantime (as long as it doesn't break any normal parsing of course).

More extensions to the parser are required, new keywords like "generic" 
and the related syntax, etc.


> DoDi: remember that bug submitters do not have to be subscribed to
> mailing list, so it's best to answer by adding a comment to the bug. (In
> this case Thomas is subscribed, just mentioning...).

Thanks for the hint :-)

DoDi

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

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

Hans-Peter Diettrich wrote:
> SourceForge.net schrieb:
> 
>> In Delphi 2009, Generics where introduced using a syntax like
>>
>> type TMyList = TObjectList<MyClass>
>>
>> This creates an TObjectList descendant using Items of MyClass.
>>
>> Also you may inherit like
>>
>> type TMyList = class(TObjectList<MyClass>) {...} end;
>>
>> Unfortunately, PasDoc ist not able to parse these files because of
>> the "<" and ">". Therefore, the whole file is not included in the
>> documentation. All that is needed is to treat "<" and ">" as part of
>> the class-name.
> 
> You're welcome to provide the according grammar, so that the parser can 
> be updated accordingly. Then we should agree about the usage of the new 
> items, so that the generators can be updated.
> 
>> Hopefully, this will be fixed soon.
> 
> This depends...
> 
> D2009 has more extensions to the grammar (local types...), for which a 
> grammar is required. PasDoc2 already has provisions to handle such 
> extensions, but any implementation deserves a grammar in the first 
> place, followed by a decision about the representation of the added 
> elements.
> 
> DoDi
> 

Indeed, contributions to Delphi 2009 syntax are welcome. I don't own any
Delphi now, so I can only offer applying the patch if someone will
submit one :)

For starters, just to make it basically parsed, I would even accept a
patch that parses it dumbly and places class name =
"TObjectList<MyClass>". That is, the simplest approach to just treat
whole "TObjectList<MyClass>" as a single identifier, without linking it
to the generic TObjectList. Of course, a better patch would be most
welcome ---I'm just saying that any crude solution will be accepted in
the meantime (as long as it doesn't break any normal parsing of course).

DoDi: remember that bug submitters do not have to be subscribed to
mailing list, so it's best to answer by adding a comment to the bug. (In
this case Thomas is subscribed, just mentioning...).

Michalis

Re: [Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[Hans-Peter D. <DrD...@ao...>]

SourceForge.net schrieb:

> In Delphi 2009, Generics where introduced using a syntax like
> 
> type TMyList = TObjectList<MyClass>
> 
> This creates an TObjectList descendant using Items of MyClass.
> 
> Also you may inherit like
> 
> type TMyList = class(TObjectList<MyClass>) {...} end;
> 
> Unfortunately, PasDoc ist not able to parse these files because of
> the "<" and ">". Therefore, the whole file is not included in the
> documentation. All that is needed is to treat "<" and ">" as part of
> the class-name.

You're welcome to provide the according grammar, so that the parser can 
be updated accordingly. Then we should agree about the usage of the new 
items, so that the generators can be updated.

> Hopefully, this will be fixed soon.

This depends...

D2009 has more extensions to the grammar (local types...), for which a 
grammar is required. PasDoc2 already has provisions to handle such 
extensions, but any implementation deserves a grammar in the first 
place, followed by a decision about the representation of the added 
elements.

DoDi

[Pasdoc-main] [ pasdoc-Bugs-2500102 ] Error when parsing Delphi 2009 files with generics

[SourceForge.net <no...@so...>]

Bugs item #2500102, was opened at 2009-01-11 22:43
Message generated for change (Tracker Item Submitted) made by Item Submitter
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=104213&aid=2500102&group_id=4213

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: parser (Delphi 200x features)
Group: 0.11.0
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Nobody/Anonymous (nobody)
Assigned to: Nobody/Anonymous (nobody)
Summary: Error when parsing Delphi 2009 files with generics

Initial Comment:
In Delphi 2009, Generics where introduced using a syntax like

type
 TMyList = TObjectList<MyClass>

This creates an TObjectList descendant using Items of MyClass.

Also you may inherit like

type
 TMyList = class(TObjectList<MyClass>)
   {...}
  end;

Unfortunately, PasDoc ist not able to parse these files because of the "<" and ">". Therefore, the whole file is not included in the documentation. All that is needed is to treat "<" and ">" as part of the class-name. 

Hopefully, this will be fixed soon.

Thomas Hummes
tho...@gm...

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=104213&aid=2500102&group_id=4213

Re: [Pasdoc-main] PasDoc2 finished

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

Hans-Peter Diettrich wrote:
> After fixing an annoying bug during destruction of the components, I 
> think that PasDoc2 is ready for use. One of the last major changes was a 
> single-component approach, for every kind of documentation.
> 
> Since no response came for the last beta versions, I consider my work on 
> PasDoc finished. Now it's up to you to decide about the future of the 
> PasDoc2 branch - leave it as it is, or merge it into the trunk.
> 

Don't worry about the lack of responses, it only means that no one else 
(including myself, admittedly) didn't have much time to play with 
development of PasDoc lately. Just to be clear: I *do* want to merge 
your work, after carefully checking and fixing it.

In fact, if all the automatic tests would succeed, I would probably just 
merge it, without much reading. I don't have much time, and I don't want 
to become a bottleneck here.

Unfortunately, many tests fail --- this is something that must be fixed 
before merging, there's no way we can apply code that breaks something 
that previously worked. Which brings me to the most important question: 
Can you reproduce these failures? I understand that you compiled PasDoc 
usually with Delphi, occasionally trying also FPC/Windows and FPC/Linux? 
Do all the tests currently succeed with Delphi?

Under FPC/Linux I get quite a lot of errors from simple "make html" 
followed by comparing "diff -wur html/ correct_output/html" inside 
tests/ subdirectory. There is "Fatal Error: Range check error" produced 
when pasdoc was run on the base tests (first mk_test call in 
tests/mk_tests.sh), and many other problems/differences later.

So my trouble is that I don't have much time for PasDoc, but I also 
can't merge blindly PasDoc2 in current state. Which means that either 
someone will fix it, or I'll be (unfortunately slowly) merging and 
fixing it along the way...

Michalis

[Pasdoc-main] PasDoc2 finished

[Hans-Peter D. <DrD...@ao...>]

After fixing an annoying bug during destruction of the components, I 
think that PasDoc2 is ready for use. One of the last major changes was a 
single-component approach, for every kind of documentation.

Since no response came for the last beta versions, I consider my work on 
PasDoc finished. Now it's up to you to decide about the future of the 
PasDoc2 branch - leave it as it is, or merge it into the trunk.

DoDi

[Pasdoc-main] [ pasdoc-Feature Requests-2241460 ] Generate separate files for members

[SourceForge.net <no...@so...>]

Feature Requests item #2241460, was opened at 2008-11-08 13:33
Message generated for change (Comment added) made by dannys9
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=2241460&group_id=4213

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Priority: 5
Private: No
Submitted By: dannys9 (dannys9)
Assigned to: Nobody/Anonymous (nobody)
Summary: Generate separate files for members

Initial Comment:
Hello,

in the current state, all members of a class are stored in a single HTML file. For large classes it is hard to navigate through the members, especially in internal documentation containing all visiblities. It would be nice to have a Delphi help like output where the description part is split into separate files for each member, containing a link back to the class and unit summary. There could be a command line option for this, like --separate-files.
I'd like to also see this implemented for the Unit output.

Regards,
Danny

----------------------------------------------------------------------

Comment By: dannys9 (dannys9)
Date: 2008-11-09 10:03

Message:
I had a look at beta7. Could it be that this version is somewhat broken?
The --ignore-leading command line option isn't working, --numericfilenames
produces files like "       1.html" instead of "00000001.html" and autodoc
produces lots of errors but no files. I could work around the first two and
then it produced correct output for my code.

But now the question is, how do I activate ItemFiles? It seems to be in
PasDoc_GenHTML.pas only for the "old" define, so I set this. But even if I
set FItemFiles to true in the TGenericHTMLDocGenerator constructor, PasDoc
will not produce separate files.

As for the filenames, I would suggest a general format of
Unit.Class.Method.N.html or Unit.Routine.N.html, where N is a counter for
the method or routine. There would be no name clashes this way.

Danny

----------------------------------------------------------------------

Comment By: Dr. Diettrich (drdiettrich)
Date: 2008-11-08 23:20

Message:
This is already implemented in PasDoc2, as an ItemFiles property. See the
last PasDoc2-beta7.

I tried to create a file structure similar to the Delphi online help,
where e.g. subroutines and methods reside in their own files. More features
may be desireable with this file structure, e.g. --numericfilenames should
be used to prevent name clashes with overloaded methods. Instead of a
command line option, a new output format 'htmlfiles' could be defined, or a
variation of 'htmlhelp'.

DoDi

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=2241460&group_id=4213

[Pasdoc-main] [ pasdoc-Feature Requests-838423 ] add a @category tag

[SourceForge.net <no...@so...>]

Feature Requests item #838423, was opened at 2003-11-08 14:06
Message generated for change (Comment added) made by drdiettrich
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=838423&group_id=4213

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Priority: 5
Private: No
Submitted By: Nobody/Anonymous (nobody)
Assigned to: Nobody/Anonymous (nobody)
Summary: add a @category tag

Initial Comment:
a @category tag would help to logically group stuff rather than only by the unit it comes from. Sometimes it just isn't possible to move code that belongs together into the same unit, for example if you are using 3rd party libraries (documented with pasdoc) and in addition have your own code.

----------------------------------------------------------------------

Comment By: Dr. Diettrich (drdiettrich)
Date: 2008-11-08 22:32

Message:
What exactly should such a tag do, what kind of output should be associated
with it?

You already can create sections in the overview file, containing groups of
links to all related items.

DoDi

----------------------------------------------------------------------

Comment By: Johannes Berg (johill)
Date: 2004-03-09 17:07

Message:
Logged In: YES 
user_id=32619

How would you use the categories? Would you want a new html page with
categories and links to units in those categories, classes in those
categories etc?
I think it would help if you could make up some fake output this would
create.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=838423&group_id=4213

[Pasdoc-main] [ pasdoc-Feature Requests-2241460 ] Generate separate files for members

[SourceForge.net <no...@so...>]

Feature Requests item #2241460, was opened at 2008-11-08 12:33
Message generated for change (Comment added) made by drdiettrich
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=2241460&group_id=4213

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Priority: 5
Private: No
Submitted By: dannys9 (dannys9)
Assigned to: Nobody/Anonymous (nobody)
Summary: Generate separate files for members

Initial Comment:
Hello,

in the current state, all members of a class are stored in a single HTML file. For large classes it is hard to navigate through the members, especially in internal documentation containing all visiblities. It would be nice to have a Delphi help like output where the description part is split into separate files for each member, containing a link back to the class and unit summary. There could be a command line option for this, like --separate-files.
I'd like to also see this implemented for the Unit output.

Regards,
Danny

----------------------------------------------------------------------

Comment By: Dr. Diettrich (drdiettrich)
Date: 2008-11-08 22:20

Message:
This is already implemented in PasDoc2, as an ItemFiles property. See the
last PasDoc2-beta7.

I tried to create a file structure similar to the Delphi online help,
where e.g. subroutines and methods reside in their own files. More features
may be desireable with this file structure, e.g. --numericfilenames should
be used to prevent name clashes with overloaded methods. Instead of a
command line option, a new output format 'htmlfiles' could be defined, or a
variation of 'htmlhelp'.

DoDi

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=2241460&group_id=4213

[Pasdoc-main] [ pasdoc-Feature Requests-2241460 ] Generate separate files for members

[SourceForge.net <no...@so...>]

Feature Requests item #2241460, was opened at 2008-11-08 13:33
Message generated for change (Tracker Item Submitted) made by Item Submitter
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=2241460&group_id=4213

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Priority: 5
Private: No
Submitted By: dannys9 (dannys9)
Assigned to: Nobody/Anonymous (nobody)
Summary: Generate separate files for members

Initial Comment:
Hello,

in the current state, all members of a class are stored in a single HTML file. For large classes it is hard to navigate through the members, especially in internal documentation containing all visiblities. It would be nice to have a Delphi help like output where the description part is split into separate files for each member, containing a link back to the class and unit summary. There could be a command line option for this, like --separate-files.
I'd like to also see this implemented for the Unit output.

Regards,
Danny

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=2241460&group_id=4213

Re: [Pasdoc-main] Group tag

[Hans-Peter D. <DrD...@ao...>]

Now groups are implemented for units and classes, including 
@groupbegin/end tags.

The HTML documentation for PasDoc2 itself is created in about 10 seconds 
on my system.

A '-' comment marker has been introduced, which allows to suppress 
unwanted comments and according warnings.

DoDi

Re: [Pasdoc-main] Group tag

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

Hans-Peter Diettrich wrote:
> Now I've implemented in PasDoc2 a first version of an group tag, for 
> enums. The tag requires an group name, and an optional group 
> description. Then the tagged members are moved into added Values lists, 
> which are shown only by the FullHTML generator.
> 
> In the next step @groupstart and @groupend tags will be added. Some 
> opinions are required, before the groups will become applicable to other 
> items, like constants. Most important: How should groups be presented in 
> the docs?
> 

Groups are not supposed to be named (groups should never need names --- 
@groupwith() takes as a parameter any identifier name already belonging 
to the group). You already read 
[http://pasdoc.sipsolutions.net/MichalisKamburelis] --- a few grouped 
items are presented as a block of declarations followed by one 
description. I attach HTML mockup how I imagine

{ One comment that describes at once three procedures
   Foo, Bar and Xyz.

   @groupbegin }
procedure Foo;
procedure Bar;
procedure Xyz;
{ @groupend }

should look like in HTMl output (TGenericHTMLDocGenerator, to be usable 
both by full HTML and htmlhelp).

If you already implemented something working in a different way, please 
at least document it in the wiki (e.g. on your home page).

Michalis

Re: [Pasdoc-main] Group tag

[Hans-Peter D. <DrD...@ao...>]

> In the next step @groupstart and @groupend tags will be added. Some 
> opinions are required, before the groups will become applicable to other 
> items, like constants. Most important: How should groups be presented in 
> the docs?

Update: groups have successfully been added to units as well :-)

DoDi

[Pasdoc-main] Group tag

[Hans-Peter D. <DrD...@ao...>]

Now I've implemented in PasDoc2 a first version of an group tag, for 
enums. The tag requires an group name, and an optional group 
description. Then the tagged members are moved into added Values lists, 
which are shown only by the FullHTML generator.

In the next step @groupstart and @groupend tags will be added. Some 
opinions are required, before the groups will become applicable to other 
items, like constants. Most important: How should groups be presented in 
the docs?

DoDi

Re: [Pasdoc-main] --ignore-leading for PasDoc2 branch - DoDi, help?

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

Forgot to actually attach ExtractDocComment_part.patch, here it is.

Michalis

[Pasdoc-main] --ignore-leading for PasDoc2 branch - DoDi, help?

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

Hi,

I just applied a patch from tobigun that adds useful --ignore-leading 
command-line option, see 
http://pasdoc.sipsolutions.net/IgnoreLeadingOption for documentation.

The patch is applied to both trunk/ and branches/PasDoc2/ (trying to 
keep them synchronized :) ). However, when applying to 
branches/PasDoc2/, I skipped the most important chunk: modification to 
ExtractDocComment to actually make this feature work. Reason: this part 
of PasDoc_Parser.pas is quite different in branches/PasDoc2/. And I was 
too lazy to investigate how to make analogous changes there, to get 
identical --ignore-leading behavior (and, possibly, almost identical 
implementation) as in trunk/.

DoDi, you know this code, can you make the changes to your 
branches/PasDoc2/ to make --ignore-leading work there? You have 
testcases for this in tests/ok_ignore_leading_* files (their correct 
output is uploaded to correct_output in WWW, so you can do 
./download_correct_tests_output.sh and compare). I'm attaching 
ExtractDocComment_part.patch which is exactly the part of the patch that 
I did not apply to PasDoc2 --- you should modify this and apply it where 
it suits best.

Thanks,
Michalis

[Pasdoc-main] [ pasdoc-Patches-2055087 ] delete/ignore leading characters in comments

[SourceForge.net <no...@so...>]

Patches item #2055087, was opened at 2008-08-16 21:51
Message generated for change (Comment added) made by kambi
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=304213&aid=2055087&group_id=4213

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
>Status: Closed
>Resolution: Accepted
Priority: 5
Private: No
Submitted By: tobigun (tobigun)
>Assigned to: Michalis Kamburelis (kambi)
Summary: delete/ignore leading characters in comments

Initial Comment:
Borland proposes a very (in my opinion) messy comment style in their styleguide. 

{ This is a comment.
  Second line. 
  Third line. }
MyVar: integer;
{ This is another comment.
  Second line.
  Third line. }
MyVar2: string;

It is difficult to separate comments from code, especially if code and comments change very often. Even with syntax-highlighting turned on its hard to distinguish both. Code folding might be a workaround but is not available on all editors.

Javadoc, Doxygen or phpDocumenter comments are much more easier to read and look much better.
There already was a feature request to support this style:
http://pasdoc.sipsolutions.net/WantedDeleteFirstChar

To be able to use such comments I changed the parser a little bit. The changes were applied to pasdoc 0.11.0 and submitted as a patch.

To ignore leading characters start pasdoc with the new command-line option --ignore-leading, e.g.:

pasdoc --ignore-leading=* my.pas

This will ignore all leading '*'-characters in '{' and '(*' comments, e.g. in

{*
 * Test
 *}

or 

{****************************
 * Test2
 ****************************}

Note that consecutive occurances of the character are ignored too (this corresponds to the Javadoc behavior).
The number of spaces preceding the character to ignore is irrelevant.

Trailing characters (e.g. '* MyTest *') are not removed from the comments, Javadoc does not handle them either.

As ignore-leading is a string-option you can even assign a string to it instead of a single character, e.g. '--ignore-leading=*!' although I would not encourage this.

The new option does not interfere with the --staronly or --marker options as these are handled before the characters are stripped.

Some further examples:

{**
 * --ignore-leading=* works with --staronly 
 *}

{###############################
 # --ignore-leading=#
 ###############################}

(*#?
  #? multiple chars can be ignored too 
  #? --ignore-leading=#?
  #?*)

{*
*   count of preceding whitespace does not matter
  * count of preceding whitespace does not matter
 **** consecutive characters are ignored too
    as in Javadoc not all lines have to start with the character
 *}

----------------------------------------------------------------------

>Comment By: Michalis Kamburelis (kambi)
Date: 2008-09-16 16:02

Message:
The patch is perfect, committed to trunk. Thank you!

Your tests are also committed (to tests/ subdir: ok_ignore_leading.pas,
ok_ignore_leading_star.pas, ok_ignore_leading_hash.pas,
ok_ignore_leading_length2.pas, called by tests/scripts/mk_tests.sh) so they
are checked automatically.

I wrote a short documentation on
http://pasdoc.sipsolutions.net/IgnoreLeadingOption (feel free to edit and
improve).

----------------------------------------------------------------------

Comment By: tobigun (tobigun)
Date: 2008-08-16 21:56

Message:
Logged In: YES 
user_id=1751006
Originator: YES

Trailing whitespaces were removed in the examples after submitting them,
so they look a little strange.
They were supposed to be indented like this:
1{*
2 * Example
3 *}
File Added: ignore_leading_chars.zip

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=304213&aid=2055087&group_id=4213