Documentation Generator Tool

Classic Servoy
1

I’m having some problems with this tool that I hope you can help me with.

We have a plugin with some sub objects that I think I correctly documented with the @ServoyDocumented tags (I checked the source and I did a bit the same thing like the window plugin).
The packages are organized like
com.xxx.plugin → package containing the IClientPlugin object and it’s provider
The other sub objects are inside packages named depending on it’s functionality like:
com.xxx.ftp
com.xxx.url
…

My problem is when I click in the project and do “Servoy → Generate Documentation XMLs for Plugins and Beans” I always get “No documentation XML files were generated. …”.
If I click individually in each package and do “Servoy → Generate single documentation XML” it works, but then, only the documentation for the main functions present in the IClientPlugin provider object appear in Servoy developer.
I tried to copy the documentation from one of the sub modules xml file inside the main file and it works, so I suppose we can only have one file per plugin?
Why can’t I generate the documentation from the project folder for all the sub objects? And why it doesn’t work with multiple individual files for each object?

Also, how could I automate the creation of the documentation when I build the plugin jar? Is it possible to call this tool from ANT?

Thanks in advance

2

Your classes implement IScriptable? A scriptable class should look like this (I think):

@ServoyDocumented
public class MyClass implements IScriptable {
}
3

And I generate the documentation per package…

4

yes, of course they implement IScriptable.

I’m able to generate the documentation, but then it doesn’t appear in developer.

I’ll separate my questions by points so it’s maybe simpler:

  • The documentation should be in only one file or multiple?
  • If one file, how can i generate this only one file for all the packages? (instead of generate package by package and then copy past in only one)
  • If multiple, where should they be so it works? (I tried to put them inside the sub package but it’s not working, for ex: com/xxx/url/servoy-extension.xml)
  • There’s some special way to organize the packages so the option “Generate Documentation XMLs for Plugins and Beans” works?
  • how could I automate the creation of the documentation when I build the plugin jar? Is it possible to call this tool from ANT?
5

I try to answer, but I might be wrong in some cases:

  • The documentation should be in only one file or multiple?

I think one file, yes

  • If one file, how can i generate this only one file for all the packages? (instead of generate package by package and then copy past in only one)

Don’t think you can. Usually, I’d say, IScriptable classes reside in one package, your plugin code. That might wrap other packages, but classes that expose functionality to Servoy scripting are usually in one package only, apart from maybe constants (at least that is the case for all plugins I have written and the ones I know from Servoy).

  • There’s some special way to organize the packages so the option “Generate Documentation XMLs for Plugins and Beans” works?

See above, usually one package for scripting (com.xy.myplugin)

  • how could I automate the creation of the documentation when I build the plugin jar? Is it possible to call this tool from ANT?

Probably, but I don’t know. Maybe one of our developers sees this and can answer…

6

I am in the middle of updating my plugins with documentations so this is from limited experience…

jbrancoIF:

  • The documentation should be in only one file or multiple?

I have all plugin and bean implementations in 2 separate packages.
Right now I create one xml per component (plugin and bean) so that means 2 files.

jbrancoIF:
– If one file, how can i generate this only one file for all the packages? (instead of generate package by package and then copy past in only one)

I don’t know I have created my own plugin for this because I use IntelliJ.
I generate both files (if applicable) from the source root into their respective package.

jbrancoIF:
– If multiple, where should they be so it works? (I tried to put them inside the sub package but it’s not working, for ex: com/xxx/url/servoy-extension.xml)

As far as I can see from my own experience the file should be in the same package as the IScriptable implementations.

jbrancoIF:
– There’s some special way to organize the packages so the option “Generate Documentation XMLs for Plugins and Beans” works?

I have not used the plugin so I can’t tell.

jbrancoIF:
– how could I automate the creation of the documentation when I build the plugin jar? Is it possible to call this tool from ANT?

In IntelliJ it is possible to create a macro triggering the plugin. Maybe something like that is also possible in Eclipse.

7

OK, I found it this week.

This works with ‘only’ one xml file per plugin, bean or combination of both.

I have mine in the same folder in the plugin and IScriptable file(s) and that works as expected.

8

Sorry for the big delay, but I’ve not been in the forum lately.

You are right about the one file. The key to generate the one file in one go is to have all the packages as a sub-package of the one implementing the IClientPlugin.

Example:
com.xxx.plugin → package containing the IClientPlugin object and it’s provider
com.xxx.plugin.ftp
com.xxx.plugin.url
…

Right click on the com.xxx.plugin → Servoy → Generate Documentation XMLs for Plugins and Beans

Now the only question left unanswered:

  • how could I automate the creation of the documentation when I build the plugin jar? Is it possible to call this tool from ANT?
9

I think you can’t.

You can start an external process from ant or create your own ant task.
Both are not hard to do.

But what you want is kick off a plugin inside eclipse.
I am not aware of eclipse offering such functionality.

Johan?