Extending FPDoc

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

Extending FPDoc

Darius Blaszyk
Hi there,

For Lazarus I have made a tool called LazDoc that attempts to integrate a
documentation editing tool with the IDE. Depending on the position of the
cursor on the source editor, the appropriate documentation tag is searched
and then selected in the editor.
Anyway, while I was working on the tool, I realized that some additional
tags would be very usefull.

todo:
Here you can enter todo items in your code. Later after documentation
generation, an additional summary page is generated with an overview of
the todo items.

notes:
Here you can enter notes in your source. They coud be remarks for instance
for other developers, or just plain reminders for yourself.

I don't know how others feel about this, but it's sure I cannot do it
myself. Perhaps someone can help me here?? Just an explanation on how to
handle and where to look would also be nice.

Darius Blaszijk




_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Sebastian Günther
[hidden email] schrieb:

> Hi there,
>
> For Lazarus I have made a tool called LazDoc that attempts to integrate a
> documentation editing tool with the IDE. Depending on the position of the
> cursor on the source editor, the appropriate documentation tag is searched
> and then selected in the editor.
> Anyway, while I was working on the tool, I realized that some additional
> tags would be very usefull.
>
> todo:
> Here you can enter todo items in your code. Later after documentation
> generation, an additional summary page is generated with an overview of
> the todo items.
>
> notes:
> Here you can enter notes in your source. They coud be remarks for instance
> for other developers, or just plain reminders for yourself.
>
> I don't know how others feel about this, but it's sure I cannot do it
> myself. Perhaps someone can help me here?? Just an explanation on how to
> handle and where to look would also be nice.

I think I can easily add this. I think it would be sufficient to 'just'
support it, without usage within the doc writers?


- Sebastian
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Michael Van Canneyt
In reply to this post by Darius Blaszyk


On Fri, 16 Sep 2005 [hidden email] wrote:

> Hi there,
>
> For Lazarus I have made a tool called LazDoc that attempts to integrate a
> documentation editing tool with the IDE. Depending on the position of the
> cursor on the source editor, the appropriate documentation tag is searched
> and then selected in the editor.
> Anyway, while I was working on the tool, I realized that some additional
> tags would be very usefull.
>
> todo:
> Here you can enter todo items in your code. Later after documentation
> generation, an additional summary page is generated with an overview of
> the todo items.
>
> notes:
> Here you can enter notes in your source. They coud be remarks for instance
> for other developers, or just plain reminders for yourself.
>
> I don't know how others feel about this, but it's sure I cannot do it
> myself. Perhaps someone can help me here?? Just an explanation on how to
> handle and where to look would also be nice.

I'd rather you keep these todo separate. It'll slow down parsing
(which is already horribly slow) and I see no added value. If you must
really use it inside the file, just use special formatting of comments:
<!-- %TODO% Some note text for authors -->

In lazarus, you could even store the TODO in a separate file. If I'm correct,
Lazarus has already a TODO system.

What concerns notes, there is already a <topic> node. It is meant for 'Extra' text.
You can use that inside the package or module node.

At the level of the package, you can nest topics:

<topic name="PackageNotes">
  <short>Notes For this Package</note>
  <topic name="Note1">
  <short>Remember to do this</short>
  <descr>more note text</descr>
  </topic>
</topic>

At the level of a module, you can't nest topics, but there you could use a
description list:

<topic name="ModuleNotes">
<short>Remember to do this</short>
<descr>
  <dl>
  <dt>Note 1</dt><dd>more note text</dd>
  </dl>
</descr>
</topic>
it's easy to parse with the XML engine.

You should be able to get a long way with this without needing to change anything in FPDoc.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Sebastian Günther
Michael Van Canneyt schrieb:
>
> I'd rather you keep these todo separate. It'll slow down parsing
> (which is already horribly slow)

Huh? Really?

A small reminder: FPDoc can support different backends, the XML storage
is just the only one currently implemented. We can talk about this
anytime...


- Sebastian
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Florian Klämpfl
Sebastian Günther wrote:

> Michael Van Canneyt schrieb:
>
>>I'd rather you keep these todo separate. It'll slow down parsing
>>(which is already horribly slow)
>
>
> Huh? Really?
>
> A small reminder: FPDoc can support different backends, the XML storage
> is just the only one currently implemented. We can talk about this
> anytime...

I would prefer to profile the xml reader and see if we can improve it.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Sebastian Günther
Florian Klämpfl schrieb:
>
> I would prefer to profile the xml reader and see if we can improve it.

Yes, but I don't see this mutually exclusive :)


- Sebastian
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Michael Van Canneyt
In reply to this post by Sebastian Günther


On Fri, 16 Sep 2005, Sebastian Günther wrote:

> Michael Van Canneyt schrieb:
> >
> > I'd rather you keep these todo separate. It'll slow down parsing
> > (which is already horribly slow)
>
> Huh? Really?

I didn't mean the FPC implementation specifically, but XML in general
is slow to parse.

> A small reminder: FPDoc can support different backends, the XML storage
> is just the only one currently implemented. We can talk about this
> anytime...

I know, but this would require a major rewrite of FPDoc.
The TDOMElement is deeply rooted in the structure.
And you need the XML anyway for transforming the pseudo-html, so I see
no gain in having another backend.

And anyway, I don't see the need for the proposed changes, see my other
mail.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Sebastian Günther
Michael Van Canneyt schrieb:
>
> I didn't mean the FPC implementation specifically, but XML in general
> is slow to parse.

Yes


> I know, but this would require a major rewrite of FPDoc.
> The TDOMElement is deeply rooted in the structure.
> And you need the XML anyway for transforming the pseudo-html, so I see
> no gain in having another backend.

This is not quite true. FPDoc can work with XML fragments, which you can
store in a database. Looking up elements would be much faster then.


> And anyway, I don't see the need for the proposed changes, see my other
> mail.

yes...


- Sebastian
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Michael Van Canneyt


On Fri, 16 Sep 2005, Sebastian Günther wrote:

> Michael Van Canneyt schrieb:
> >
> > I didn't mean the FPC implementation specifically, but XML in general
> > is slow to parse.
>
> Yes
>
>
> > I know, but this would require a major rewrite of FPDoc.
> > The TDOMElement is deeply rooted in the structure.
> > And you need the XML anyway for transforming the pseudo-html, so I see
> > no gain in having another backend.
>
> This is not quite true. FPDoc can work with XML fragments, which you can
> store in a database. Looking up elements would be much faster then.
Yes, I know. I even have a database model ready for it...

My plan was to have the descriptions in the database, and produce
a correct XML file which is then fed to fpdoc.

I'm not yet convinced that having a DB backend to FPDoc will be so trivial,
but if you think it's easy to do: I'm all for it :-)

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Florian Klämpfl
In reply to this post by Sebastian Günther
Sebastian Günther wrote:
> Florian Klämpfl schrieb:
>
>>I would prefer to profile the xml reader and see if we can improve it.
>
>
> Yes, but I don't see this mutually exclusive :)

Can somebody send me profiler output? Or how can it be reproduced?
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Michael Van Canneyt


On Sat, 17 Sep 2005, Florian Klämpfl wrote:

> Sebastian Günther wrote:
> > Florian Klämpfl schrieb:
> >
> > > I would prefer to profile the xml reader and see if we can improve it.
> >
> >
> > Yes, but I don't see this mutually exclusive :)
>
> Can somebody send me profiler output? Or how can it be reproduced?

Just run fpdoc on the documentation. Replace your binary with a binary
containing profiluing info and run "make rtl.inc" in the docs directory.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Sebastian Günther
In reply to this post by Michael Van Canneyt
Michael Van Canneyt schrieb:
>
> I'm not yet convinced that having a DB backend to FPDoc will be so trivial,
> but if you think it's easy to do: I'm all for it :-)

Okay. I'll try to have a look on this within the next days. At the
moment we have a state of emergency, as Oktoberfest just startet ;)
(i.e. don't count on me tomorrow, but Monday should be fine.)


- Sebastian
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Darius Blaszyk
In reply to this post by Michael Van Canneyt
On Fri, 2005-09-16 at 22:17, Michael Van Canneyt wrote:
> I'd rather you keep these todo separate. It'll slow down parsing
> (which is already horribly slow) and I see no added value. If you must
Could you elaborate on that?? I don't see a problem in adding a tag.
While indeed it will slow down parsing by a few mSec per node, the
generated pages will not suffer from this at all. Instead more useful
text will be shown for developers. Because that's the audience the
documentation is meant for right??

> In lazarus, you could even store the TODO in a separate file. If I'm correct,
> Lazarus has already a TODO system.
True, but it does not show in the documentation obviously.

> What concerns notes, there is already a <topic> node. It is meant for 'Extra' text.
> You can use that inside the package or module node.
Ok, good to hear, but can I use it also at the element level?? Although
pakage notes are usefull, they will never get into that much detail as
element notes. What I have in mind are detailed notes per element on
certain aspects in the code.

Darius


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Darius Blaszyk
In reply to this post by Sebastian Günther
On Fri, 2005-09-16 at 22:14, Sebastian Günther wrote:

> I think I can easily add this. I think it would be sufficient to 'just'
> support it, without usage within the doc writers?

I don't see much use in that. If text does not appear back in the
documentation then there is no point adding text.

Darius


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Extending FPDoc

Michael Van Canneyt
In reply to this post by Darius Blaszyk


On Sun, 18 Sep 2005, Darius Blaszijk wrote:

> On Fri, 2005-09-16 at 22:17, Michael Van Canneyt wrote:
> > I'd rather you keep these todo separate. It'll slow down parsing
> > (which is already horribly slow) and I see no added value. If you must
> Could you elaborate on that?? I don't see a problem in adding a tag.
> While indeed it will slow down parsing by a few mSec per node, the
> generated pages will not suffer from this at all. Instead more useful
> text will be shown for developers. Because that's the audience the
> documentation is meant for right??

If it is useful for everyone (i.e. end-users), why don't you put it in
the documentation itself ?

>
> > In lazarus, you could even store the TODO in a separate file. If I'm correct,
> > Lazarus has already a TODO system.
> True, but it does not show in the documentation obviously.

TODO's should not be in the documentation. The documentation is
for the end-users of code. The TODO is for the developer of the code.
That is why you should use lazarus' TODO system for it.

John Doe is not interested in reading things like
'Optimize the code to use faster TFPList instead of TList'
He wants to know what a call does, or what the effect is
of setting a property. How this is achieved is not of interest.

>
> > What concerns notes, there is already a <topic> node. It is meant for 'Extra' text.
> > You can use that inside the package or module node.
> Ok, good to hear, but can I use it also at the element level?? Although
> pakage notes are usefull, they will never get into that much detail as
> element notes. What I have in mind are detailed notes per element on
> certain aspects in the code.

You can't. It is not meant for that, either.

Keep in mind that the documentation is meant for end-users,
not for the maintainers of the code. For the maintainers,
there is the TODO list of Lazarus.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal