ZeelandNet Webmail

Hi,

Today I was playing with FPDoc and I
decided to add creating the documents as a target to fpmake which seems logical to me. I only did a very basic implementation to show tghe principle so someone (Joost / Michael??) can shoot at it first before I burn too much time on it.

The bugreport is
here:
http://bugs.freepascal.org/view.php?id=18050 [1]

Regards, Darius

Links:
------
[1] http://bugs.freepascal.org/view.php?id=18050

I think it is a good and valuable idea.
Do you have any plans to add more functionality to it ?

Michael.

I think it is a good and valuable idea. Do you have any plans to add more functionality to it ?

I was thinking about adding a few more helper functions, such as adding documentation for whole directories at a time. Also the documentation output should be possible to be set, currently it's in the same directory as fpmake is in. Other than that I have no immediate plans. Do you have something specific in mind?

Regards, Darius

- Selection of output format ?
- Add to zip ?

Michael.

Good ones. I could add some more settings (output format in this case) to TTargets. Is that ok? Please have a look at how I implemented it in the first place.

Adding the docs to the zipfile should be trivial.

Darius

- Selection of output format ? - Add to zip ?

I created a new patch that implements these options. Can someone please review the patch and comment on it. Are there any other frequently used settings or conditions regarding fpdoc that should be taken in the patch? I'm happy to apply them.

http://bugs.freepascal.org/view.php?id=18050

Regards, Darius

Tomorrow I will look at both batches.

Thanks for your efforts, it's hugely appreciated.

Michael.

I've been thinking about the folder structure for fpdoc xml files. Analog to bin and example files I would like to have the xml files in the default location called fpdoc. The output will be sent to the folder called docs. From where they can be installed. Of course the locations should be overidable.

Regarding Marco's comment on Mantis however I'm not sure it will be possible to link xml and sourcefiles automatically, therefore I'm not sure it could work with a default fpdoc folder. Some comments would be appreciated.

Regards, Darius

That concept seems OK to me.
Maybe --descr-folder and --doc-folder options need to be made then.

Regarding Marco's comment on Mantis however I'm not sure it will be possible to link xml and sourcefiles automatically, therefore I'm not sure it could work with a default fpdoc folder. Some comments would be appreciated.

? Not sure I understand wat you mean here. Marco's remark is about order of the units. What does that have to do with linking XML and source automatically ?

Michael.

Indeed.

If we link xml and source files automatically there is no way guaranteeing the order. That was my concern. The current implementation forces the order because it follows the order in which doc files were added in fpmake.pp. But if we adhere to this method, then there is no "special" need for a fpdoc folder.

Darius

--doc-folder has been implemented. --descr-folder not yet, as we need to reach consensus on how to handle order dependency of fpdoc

Darius

Well, fpmake contains the dependencies of the units. Therefor you should be able to place the units in the correct order. So my idea would be to enforce the order by looking at the dependencies.

All that is needed is to list the units that should be documented; The engine can then look in the list of dependencies, and if there are dependencies found, they can be added first.

Michael.

I suppose it should look like this then:

T := P.Targets.AddFPDoc('input.pas', 'descr.xml');
T.Dependencies.Add('myunit1.pas');
T.Dependencies.Add('myunit2.pas');
Will generate the following command;

fpdoc --input=myunit1.pas --input=myunit2.pas --input=input.pas --descr=descr.xml

Did I understand it correctly?

Regards, Darius

I believe he meant that you can get the dependencies from the already added units.

E.g. (from rtl/fpmake.pp):

T:=P.Targets.AddUnit('classes.pp');
T.IncludePath.Add('objpas/classes');
With T.Dependencies do
   begin
     AddUnit('sysutils');
     AddUnit('types');
     AddUnit('typinfo');
     AddUnit('unix',AllUnixOSes);
     AddUnit('windows',AllWindowsOSes);
   end;

You already know from here that 'classes.pp' depends on those units, so you might use those already defined dependencies to automatically add those units to fpdoc as well (I don't know how exactly you can and need to do it, but that's the theory) if you want to generate the documentation for 'classes'.

Regards,
Sven

Yup, we're talking about the same (though I should have used AddUnit as you did). I just wanted to have confirmation (also regarding fpdoc command-line options).

Darius

Uploaded a new patch to Mantis implementing the above mentioned functionality.

Darius