Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / fpc-pascal / 2007-08

fpdoc cleanup after a refactor

7 messages · 3 people ·

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Graeme Geldenhuys

Hi,

What is the best method to clean up documentation files after a class or unit refactor was done. My xml files are all outdated now - referencing methods or sometimes even classes that don't exist anymore.

What is the options available to me. Lets hope I have more choices than to recreate the xml file with makeskel and manually copy and paste all relevant documentation into the new xml file. This will take forever because the nodes are not in the same order, etc.!

If there is no easy solution with fpdoc, my other long term solution would possibly be to move back to PasDoc with embedded docs. That seem to be easier to manage with evolving code. That also means I would have to write a new HTML output format for PasDoc, because I really like the fpdoc's generated HTML layout. PasDoc's default HTML layout is just crap and to busy.

ps:
Will the fpdoc.css file used by FPC and Lazarus docs be included as the default in the next FPC release? The default css file in FPC 2.0.4 look crap compared to the one used on the web.

Regards,
- Graeme -

Michael Van Canneyt
to Graeme Geldenhuys
Graeme Geldenhuys wrote 11 lines
Hi, What is the best method to clean up documentation files after a class or unit refactor was done. My xml files are all outdated now - referencing methods or sometimes even classes that don't exist anymore. What is the options available to me. Lets hope I have more choices than to recreate the xml file with makeskel and manually copy and paste all relevant documentation into the new xml file. This will take forever because the nodes are not in the same order, etc.!

Well, makeskel has an update option. It will generate nodes for all missing elements.

What more can you expect ?
We could add some map feature so it remaps nodes.
But that would mean you'll need to create the map.

Show quoted text 11 lines
If there is no easy solution with fpdoc, my other long term solution would possibly be to move back to PasDoc with embedded docs. That seem to be easier to manage with evolving code. That also means I would have to write a new HTML output format for PasDoc, because I really like the fpdoc's generated HTML layout. PasDoc's default HTML layout is just crap and to busy. ps: Will the fpdoc.css file used by FPC and Lazarus docs be included as the default in the next FPC release? The default css file in FPC 2.0.4 look crap compared to the one used on the web.

? It's the same file.

Michael.

Graeme Geldenhuys
to Michael Van Canneyt
Michael Van Canneyt wrote
Well, makeskel has an update option. It will generate nodes for all missing elements.

Sorry, maybe I was a bit unclear. I know it's got the update option. So after a refactor, I update my xml with makeskel. Now my description xml file contains new and old (outdated) notes. After a while I have a lot of outdated nodes in the xml and would like to some cleanup.

Is there a way for makeskel or some other tool to notify (generate some list) of outdate nodes (descriptions nodes that can't be matched to the source files anymore)?
If 'lazde' doesn't have this feature, maybe it will be worth the effort adding it in.

We could add some map feature so it remaps nodes. But that would mean you'll need to create the map.

Nah, that sounds like work! :) Maybe we can improve 'lazde' so we can Cut, Paste and Rename nodes. That would at least help a bit.

Show quoted text 6 lines
> ps: > Will the fpdoc.css file used by FPC and Lazarus docs be included as > the default in the next FPC release? The default css file in FPC > 2.0.4 look crap compared to the one used on the web. ? It's the same file.

Not in my copy. The one with 2.0.4 generates black text on a white background with a Courier font for the code. The one FPC and Lazarus used generates blue text on blue/white background with a nice font (not Courier).

Peter (from tiOPF) also downloaded FPC 2.0.4 and Lazarus a few days ago and complained about the same thing. He said his HTML output looks nothing like the FPC docs or the tiOPF docs I host (which uses the css file I manually copied from the FPC website)

Regards,
- Graeme -

Vincent Snijders
to Graeme Geldenhuys
Graeme Geldenhuys wrote 15 lines
>> ps: >> Will the fpdoc.css file used by FPC and Lazarus docs be included as >> the default in the next FPC release? The default css file in FPC >> 2.0.4 look crap compared to the one used on the web. > ? It's the same file. Not in my copy. The one with 2.0.4 generates black text on a white background with a Courier font for the code. The one FPC and Lazarus used generates blue text on blue/white background with a nice font (not Courier). Peter (from tiOPF) also downloaded FPC 2.0.4 and Lazarus a few days ago and complained about the same thing. He said his HTML output looks nothing like the FPC docs or the tiOPF docs I host (which uses the css file I manually copied from the FPC website)

I see no difference between:
http://svn.freepascal.org/svn/lazarus/trunk/docs/html/fpdoc.css (lazarus svn and lazarus release)
and
http://svn.freepascal.org/svn/lazarus/trunk/docs/html/fpdoc.css (current lazarus doc website).

Vincent

Vincent Snijders
to Vincent Snijders
Vincent Snijders wrote 21 lines
Graeme Geldenhuys schreef: >>> ps: >>> Will the fpdoc.css file used by FPC and Lazarus docs be included as >>> the default in the next FPC release? The default css file in FPC >>> 2.0.4 look crap compared to the one used on the web. >> ? It's the same file. > > Not in my copy. The one with 2.0.4 generates black text on a white > background with a Courier font for the code. The one FPC and Lazarus > used generates blue text on blue/white background with a nice font > (not Courier). > > Peter (from tiOPF) also downloaded FPC 2.0.4 and Lazarus a few days > ago and complained about the same thing. He said his HTML output looks > nothing like the FPC docs or the tiOPF docs I host (which uses the css > file I manually copied from the FPC website) I see no difference between: http://svn.freepascal.org/svn/lazarus/trunk/docs/html/fpdoc.css (lazarus svn and lazarus release) and

<snip wrong link> http://lazarus-ccr.sourceforge.net/docs/lcl/fpdoc.css (current

lazarus doc website).

Vincent

Michael Van Canneyt
to Graeme Geldenhuys: Sorry, maybe I was a bit unclear. I know it's got the update option. So after a refactor,…
Graeme Geldenhuys wrote 9 lines
On 14/08/07, Michael Van Canneyt wrote: > > Well, makeskel has an update option. It will generate nodes for all > missing elements. Sorry, maybe I was a bit unclear. I know it's got the update option. So after a refactor, I update my xml with makeskel. Now my description xml file contains new and old (outdated) notes. After a while I have a lot of outdated nodes in the xml and would like to some cleanup.

This was clear.

Show quoted text 6 lines
Is there a way for makeskel or some other tool to notify (generate some list) of outdate nodes (descriptions nodes that can't be matched to the source files anymore)? If 'lazde' doesn't have this feature, maybe it will be worth the effort adding it in.

fpdoc notifies you of nodes it cannot find. The opposite (unused nodes) has not yet been done, but should be easy to add.

Show quoted text 6 lines
> We could add some map feature so it remaps nodes. > But that would mean you'll need to create the map. Nah, that sounds like work! :) Maybe we can improve 'lazde' so we can Cut, Paste and Rename nodes. That would at least help a bit.

This should be feasible; It's XML. All you need to do is traverse nodes and do a search and replace on ID and name attributes.

Show quoted text 13 lines
> > ps: > > Will the fpdoc.css file used by FPC and Lazarus docs be included as > > the default in the next FPC release? The default css file in FPC > > 2.0.4 look crap compared to the one used on the web. > > ? It's the same file. Not in my copy. The one with 2.0.4 generates black text on a white background with a Courier font for the code. The one FPC and Lazarus used generates blue text on blue/white background with a nice font (not Courier).

Strange. I know I never changed the file since it was first created :-)

Michael.

Graeme Geldenhuys
to Michael Van Canneyt
Michael Van Canneyt wrote
fpdoc notifies you of nodes it cannot find. The opposite (unused nodes) has not yet been done, but should be easy to add.

I'll have to play with fpdoc some more... I'm currently writing a little fpGUI app (just because I can <smile>), but will probably end up being a console app that helps me generate documentation. Inspired by the new makefiles alternative. It will read a config file for input and output directories for *.pas, *.xml and *.html. I got tired of constantly editing scripts to include new units or directory paths. :-)

This should be feasible; It's XML. All you need to do is traverse nodes and do a search and replace on ID and name attributes.

Yeah, I noticed the XML makeskel generates is very basic (a flat hierarchy). I'm thinking of implementing something like Lazarus's 'Refactoring -> Rename Identifiers' feature, plus a few more nice toys for the docs. Should be nice to have.

Strange. I know I never changed the file since it was first created :-)

As long as the new release has the pretty one. :) In the mean time I gave Peter a copy of mine.

Regards,
- Graeme -