Documentation Generator Tool

Questions and answers on developing, deploying and using plugins and JavaBeans

Documentation Generator Tool

Postby jbrancoIF » Mon Nov 14, 2016 10:40 am

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
João Branco
InfoForm SA

Servoy 8.1.2
Windows 7 64 bits
jbrancoIF
 
Posts: 61
Joined: Tue Jan 10, 2012 11:29 am

Re: Documentation Generator Tool

Postby patrick » Mon Nov 14, 2016 10:49 am

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

Code: Select all
@ServoyDocumented
public class MyClass implements IScriptable {
}
Patrick Ruhsert
Servoy DACH
patrick
 
Posts: 3598
Joined: Wed Jun 11, 2003 10:33 am
Location: Munich, Germany

Re: Documentation Generator Tool

Postby patrick » Mon Nov 14, 2016 10:50 am

And I generate the documentation per package...
Patrick Ruhsert
Servoy DACH
patrick
 
Posts: 3598
Joined: Wed Jun 11, 2003 10:33 am
Location: Munich, Germany

Re: Documentation Generator Tool

Postby jbrancoIF » Mon Nov 14, 2016 1:15 pm

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?
João Branco
InfoForm SA

Servoy 8.1.2
Windows 7 64 bits
jbrancoIF
 
Posts: 61
Joined: Tue Jan 10, 2012 11:29 am

Re: Documentation Generator Tool

Postby patrick » Mon Nov 14, 2016 6:16 pm

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...
Patrick Ruhsert
Servoy DACH
patrick
 
Posts: 3598
Joined: Wed Jun 11, 2003 10:33 am
Location: Munich, Germany

Re: Documentation Generator Tool

Postby IT2Be » Sat Dec 03, 2016 12:55 pm

I am in the middle of updating my plugins with documentations so this is from limited experience...
jbrancoIF wrote:- 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 wrote:-- 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 wrote:-- 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 wrote:-- 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 wrote:-- 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.
Marcel J.G. Trapman (IT2BE)
SAN partner - Freelance Java and Servoy
Servoy Components - IT2BE Plug-ins and Beans for Servoy
ServoyForge - Open Source Components for Servoy
User avatar
IT2Be
Servoy Expert
 
Posts: 4763
Joined: Tue Oct 14, 2003 7:09 pm
Location: Germany

Re: Documentation Generator Tool

Postby IT2Be » Sun Dec 11, 2016 11:55 am

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.
Marcel J.G. Trapman (IT2BE)
SAN partner - Freelance Java and Servoy
Servoy Components - IT2BE Plug-ins and Beans for Servoy
ServoyForge - Open Source Components for Servoy
User avatar
IT2Be
Servoy Expert
 
Posts: 4763
Joined: Tue Oct 14, 2003 7:09 pm
Location: Germany

Re: Documentation Generator Tool

Postby jbrancoIF » Mon Jan 16, 2017 6:06 pm

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?
João Branco
InfoForm SA

Servoy 8.1.2
Windows 7 64 bits
jbrancoIF
 
Posts: 61
Joined: Tue Jan 10, 2012 11:29 am

Re: Documentation Generator Tool

Postby IT2Be » Mon Jan 16, 2017 6:12 pm

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?
Marcel J.G. Trapman (IT2BE)
SAN partner - Freelance Java and Servoy
Servoy Components - IT2BE Plug-ins and Beans for Servoy
ServoyForge - Open Source Components for Servoy
User avatar
IT2Be
Servoy Expert
 
Posts: 4763
Joined: Tue Oct 14, 2003 7:09 pm
Location: Germany


Return to Plugins and Beans

Who is online

Users browsing this forum: No registered users and 4 guests