[xwiki-devs] Issue with maven generation of the javadoc for SRD
Hi, I found an issue with the maven project to generate the javadocs for SRD. Apparently all the internal packages are ignored. This is no necessarly a problem unless we want them in the javadocs. Now there is a problem as some APIs are in internal, which does not seem normal. This is the case of: org.xwiki.officeimporter.internal.script.OfficeImporterScriptService org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService Until we find a solution i've reverted to the javadocs manually generated (without the maven project). Ludovic -- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost
On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> wrote:
Hi,
I found an issue with the maven project to generate the javadocs for SRD. Apparently all the internal packages are ignored. This is no necessarly a problem unless we want them in the javadocs. Now there is a problem as some APIs are in internal, which does not seem normal.
This is the case of:
org.xwiki.officeimporter.internal.script.OfficeImporterScriptService org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService
Most of our script services are internal. For the office module I need to create a single script service (hint=office) with 3 methods getImporter(), getManager() and getViewer(). Thanks, Marius
Until we find a solution i've reverted to the javadocs manually generated (without the maven project).
Ludovic
-- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Why would script services be internal ? They should have a stable API shouldn't they ? Ludovic 2012/10/10 Marius Dumitru Florea <[email protected]>
On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> wrote:
Hi,
I found an issue with the maven project to generate the javadocs for SRD. Apparently all the internal packages are ignored. This is no necessarly a problem unless we want them in the javadocs. Now there is a problem as some APIs are in internal, which does not seem normal.
This is the case of:
org.xwiki.officeimporter.internal.script.OfficeImporterScriptService
org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService
org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService
Most of our script services are internal. For the office module I need to create a single script service (hint=office) with 3 methods getImporter(), getManager() and getViewer().
Thanks, Marius
Until we find a solution i've reverted to the javadocs manually generated (without the maven project).
Ludovic
-- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost
Hi Ludovic, On Oct 10, 2012, at 3:39 PM, Ludovic Dubost <[email protected]> wrote:
Why would script services be internal ? They should have a stable API shouldn't they ?
Yes, I agree, each Script Service should define an interface and implement it in addition to implementing ScriptService. We've been lazy and we should fix this as otherwise CLIRR won't let us know when we break scripting APIs.
Ludovic
2012/10/10 Marius Dumitru Florea <[email protected]>
On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> wrote:
Hi,
I found an issue with the maven project to generate the javadocs for SRD. Apparently all the internal packages are ignored.
This is normal and good. We don't want to show these to the user. Thanks -Vincent
This is no necessarly a problem unless we want them in the javadocs. Now there is a problem as some APIs are in internal, which does not seem normal.
This is the case of:
org.xwiki.officeimporter.internal.script.OfficeImporterScriptService
org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService
org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService
Most of our script services are internal. For the office module I need to create a single script service (hint=office) with 3 methods getImporter(), getManager() and getViewer().
Thanks, Marius
Until we find a solution i've reverted to the javadocs manually generated (without the maven project).
Ludovic
On 10/10/2012 04:30 PM, Vincent Massol wrote:
Hi Ludovic,
On Oct 10, 2012, at 3:39 PM, Ludovic Dubost <[email protected]> wrote:
Why would script services be internal ? They should have a stable API shouldn't they ? Yes, I agree, each Script Service should define an interface and implement it in addition to implementing ScriptService.
We've been lazy and we should fix this as otherwise CLIRR won't let us know when we break scripting APIs.
Wouln't it be good to start distinguish between API and SPI, and have a different set of CLIRR rules for each type ? For instance, I don't see a big benefit in not allowing new methods in such script services interfaces. In my opinion those are not designed or intended to be extended or implemented by third parties anyway. So IMO going through a VOTE everytime one adds a new method to a script service is too constraining for little value. My 2 cents Jerome
Ludovic
2012/10/10 Marius Dumitru Florea <[email protected]>
On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> wrote:
Hi,
I found an issue with the maven project to generate the javadocs for SRD. Apparently all the internal packages are ignored. This is normal and good. We don't want to show these to the user.
Thanks -Vincent
This is no necessarly a problem unless we want them in the javadocs. Now there is a problem as some APIs are in internal, which does not seem normal.
This is the case of:
org.xwiki.officeimporter.internal.script.OfficeImporterScriptService
org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService
org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService Most of our script services are internal. For the office module I need to create a single script service (hint=office) with 3 methods getImporter(), getManager() and getViewer().
Thanks, Marius
Until we find a solution i've reverted to the javadocs manually generated (without the maven project).
Ludovic
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Peace, —Jerome
On 10/10/2012 12:03 PM, Jerome Velociter wrote:
On 10/10/2012 04:30 PM, Vincent Massol wrote:
Hi Ludovic,
On Oct 10, 2012, at 3:39 PM, Ludovic Dubost <[email protected]> wrote:
Why would script services be internal ? They should have a stable API shouldn't they ? Yes, I agree, each Script Service should define an interface and implement it in addition to implementing ScriptService.
We've been lazy and we should fix this as otherwise CLIRR won't let us know when we break scripting APIs.
Wouln't it be good to start distinguish between API and SPI, and have a different set of CLIRR rules for each type ?
For instance, I don't see a big benefit in not allowing new methods in such script services interfaces. In my opinion those are not designed or intended to be extended or implemented by third parties anyway. So IMO going through a VOTE everytime one adds a new method to a script service is too constraining for little value.
My 2 cents Jerome
Totally agree. One other thing that bugs me is that a component that implements two roles will have two instances, and this makes it harder to have a class that implements both ScriptService and a specific role for that component.
Ludovic
2012/10/10 Marius Dumitru Florea <[email protected]>
On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> wrote:
Hi,
I found an issue with the maven project to generate the javadocs for SRD. Apparently all the internal packages are ignored. This is normal and good. We don't want to show these to the user.
Thanks -Vincent
This is no necessarly a problem unless we want them in the javadocs. Now there is a problem as some APIs are in internal, which does not seem normal.
This is the case of:
org.xwiki.officeimporter.internal.script.OfficeImporterScriptService
org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService
org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService Most of our script services are internal. For the office module I need to create a single script service (hint=office) with 3 methods getImporter(), getManager() and getViewer().
Thanks, Marius
Until we find a solution i've reverted to the javadocs manually generated (without the maven project).
Ludovic
-- Sergiu Dumitriu http://purl.org/net/sergiu/
On Oct 11, 2012, at 12:00 AM, Sergiu Dumitriu <[email protected]> wrote:
On 10/10/2012 12:03 PM, Jerome Velociter wrote:
On 10/10/2012 04:30 PM, Vincent Massol wrote:
Hi Ludovic,
On Oct 10, 2012, at 3:39 PM, Ludovic Dubost <[email protected]> wrote:
Why would script services be internal ? They should have a stable API shouldn't they ? Yes, I agree, each Script Service should define an interface and implement it in addition to implementing ScriptService.
We've been lazy and we should fix this as otherwise CLIRR won't let us know when we break scripting APIs.
Wouln't it be good to start distinguish between API and SPI, and have a different set of CLIRR rules for each type ?
For instance, I don't see a big benefit in not allowing new methods in such script services interfaces. In my opinion those are not designed or intended to be extended or implemented by third parties anyway. So IMO going through a VOTE everytime one adds a new method to a script service is too constraining for little value.
My 2 cents Jerome
Totally agree.
Yes we can start brainstorming about it. It's a lot of work. We need to define precisely what we call SPI and what we call API and then define rules for SPI package name (probably needs "spi" in the package name or api needs to be put in an "api" package name), need to think about migration from what we have to the target, etc.
One other thing that bugs me is that a component that implements two roles will have two instances, and this makes it harder to have a class that implements both ScriptService and a specific role for that component.
Yes but that's not needed. The script service only needs to implement 1 component role, the interface doesn't have to be a role. Thanks -Vincent
Ludovic
2012/10/10 Marius Dumitru Florea <[email protected]>
On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> wrote:
Hi,
I found an issue with the maven project to generate the javadocs for SRD. Apparently all the internal packages are ignored. This is normal and good. We don't want to show these to the user.
Thanks -Vincent
This is no necessarly a problem unless we want them in the javadocs. Now there is a problem as some APIs are in internal, which does not seem normal.
This is the case of:
org.xwiki.officeimporter.internal.script.OfficeImporterScriptService
org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService
org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService Most of our script services are internal. For the office module I need to create a single script service (hint=office) with 3 methods getImporter(), getManager() and getViewer().
Thanks, Marius
Until we find a solution i've reverted to the javadocs manually generated (without the maven project).
Ludovic
On 10/10/2012 06:21 PM, Vincent Massol wrote:
On Oct 11, 2012, at 12:00 AM, Sergiu Dumitriu <[email protected]> wrote:
On 10/10/2012 12:03 PM, Jerome Velociter wrote:
On 10/10/2012 04:30 PM, Vincent Massol wrote:
Hi Ludovic,
On Oct 10, 2012, at 3:39 PM, Ludovic Dubost <[email protected]> wrote:
Why would script services be internal ? They should have a stable API shouldn't they ? Yes, I agree, each Script Service should define an interface and implement it in addition to implementing ScriptService.
We've been lazy and we should fix this as otherwise CLIRR won't let us know when we break scripting APIs.
Wouln't it be good to start distinguish between API and SPI, and have a different set of CLIRR rules for each type ?
For instance, I don't see a big benefit in not allowing new methods in such script services interfaces. In my opinion those are not designed or intended to be extended or implemented by third parties anyway. So IMO going through a VOTE everytime one adds a new method to a script service is too constraining for little value.
My 2 cents Jerome
Totally agree.
Yes we can start brainstorming about it. It's a lot of work. We need to define precisely what we call SPI and what we call API and then define rules for SPI package name (probably needs "spi" in the package name or api needs to be put in an "api" package name), need to think about migration from what we have to the target, etc.
One other thing that bugs me is that a component that implements two roles will have two instances, and this makes it harder to have a class that implements both ScriptService and a specific role for that component.
Yes but that's not needed. The script service only needs to implement 1 component role, the interface doesn't have to be a role.
It is if you want to use it not just from scripts, but from Java as well. I'm talking mostly about utilities like XMLScriptService which don't expose an internal component to scripts, but provide their own functionality.
Thanks -Vincent
Ludovic
2012/10/10 Marius Dumitru Florea <[email protected]>
On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> wrote: > Hi, > > I found an issue with the maven project to generate the javadocs for > SRD. Apparently all the internal packages are ignored. This is normal and good. We don't want to show these to the user.
Thanks -Vincent
> This is no necessarly a problem unless we want them in the javadocs. > Now there is a problem as some APIs are in internal, which does not > seem normal. > > This is the case of: > > org.xwiki.officeimporter.internal.script.OfficeImporterScriptService > org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService
> org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService Most of our script services are internal. For the office module I need to create a single script service (hint=office) with 3 methods getImporter(), getManager() and getViewer().
Thanks, Marius
> Until we find a solution i've reverted to the javadocs manually > generated (without the maven project). > > Ludovic
-- Sergiu Dumitriu http://purl.org/net/sergiu/
On Oct 11, 2012, at 3:03 PM, Sergiu Dumitriu <[email protected]> wrote:
On 10/10/2012 06:21 PM, Vincent Massol wrote:
On Oct 11, 2012, at 12:00 AM, Sergiu Dumitriu <[email protected]> wrote:
On 10/10/2012 12:03 PM, Jerome Velociter wrote:
On 10/10/2012 04:30 PM, Vincent Massol wrote:
Hi Ludovic,
On Oct 10, 2012, at 3:39 PM, Ludovic Dubost <[email protected]> wrote:
Why would script services be internal ? They should have a stable API shouldn't they ? Yes, I agree, each Script Service should define an interface and implement it in addition to implementing ScriptService.
We've been lazy and we should fix this as otherwise CLIRR won't let us know when we break scripting APIs.
Wouln't it be good to start distinguish between API and SPI, and have a different set of CLIRR rules for each type ?
For instance, I don't see a big benefit in not allowing new methods in such script services interfaces. In my opinion those are not designed or intended to be extended or implemented by third parties anyway. So IMO going through a VOTE everytime one adds a new method to a script service is too constraining for little value.
My 2 cents Jerome
Totally agree.
Yes we can start brainstorming about it. It's a lot of work. We need to define precisely what we call SPI and what we call API and then define rules for SPI package name (probably needs "spi" in the package name or api needs to be put in an "api" package name), need to think about migration from what we have to the target, etc.
One other thing that bugs me is that a component that implements two roles will have two instances, and this makes it harder to have a class that implements both ScriptService and a specific role for that component.
Yes but that's not needed. The script service only needs to implement 1 component role, the interface doesn't have to be a role.
It is if you want to use it not just from scripts, but from Java as well. I'm talking mostly about utilities like XMLScriptService which don't expose an internal component to scripts, but provide their own functionality.
Then you should have a different component since ScriptService is… a script service and thus not meant to be used from Java… I personally like the fact that a component can implement only one role. Makes a clean separation of concerns. -Vincent
Thanks -Vincent
Ludovic
2012/10/10 Marius Dumitru Florea <[email protected]>
> On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> > wrote: >> Hi, >> >> I found an issue with the maven project to generate the javadocs for >> SRD. Apparently all the internal packages are ignored. This is normal and good. We don't want to show these to the user.
Thanks -Vincent
>> This is no necessarly a problem unless we want them in the javadocs. >> Now there is a problem as some APIs are in internal, which does not >> seem normal. >> >> This is the case of: >> >> org.xwiki.officeimporter.internal.script.OfficeImporterScriptService >> > org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService > >> org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService > Most of our script services are internal. For the office module I need > to create a single script service (hint=office) with 3 methods > getImporter(), getManager() and getViewer(). > > Thanks, > Marius > >> Until we find a solution i've reverted to the javadocs manually >> generated (without the maven project). >> >> Ludovic
-- Sergiu Dumitriu http://purl.org/net/sergiu/ _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Actually ScriptServiceis not a good example since there are not supposed to have anything but calls to the actual component and convert/adapt/protect the data for scripting but there is perfectly valid use cases that are a pain to manage right now: invalidate some internal cache of a component based on events. For theses you would need to implement both the component main job and EventListener. On Thu, Oct 11, 2012 at 3:32 PM, Vincent Massol <[email protected]> wrote:
On Oct 11, 2012, at 3:03 PM, Sergiu Dumitriu <[email protected]> wrote:
On 10/10/2012 06:21 PM, Vincent Massol wrote:
On Oct 11, 2012, at 12:00 AM, Sergiu Dumitriu <[email protected]> wrote:
On 10/10/2012 12:03 PM, Jerome Velociter wrote:
On 10/10/2012 04:30 PM, Vincent Massol wrote:
Hi Ludovic,
On Oct 10, 2012, at 3:39 PM, Ludovic Dubost <[email protected]> wrote:
> Why would script services be internal ? They should have a stable API > shouldn't they ? Yes, I agree, each Script Service should define an interface and implement it in addition to implementing ScriptService.
We've been lazy and we should fix this as otherwise CLIRR won't let us know when we break scripting APIs.
Wouln't it be good to start distinguish between API and SPI, and have a different set of CLIRR rules for each type ?
For instance, I don't see a big benefit in not allowing new methods in such script services interfaces. In my opinion those are not designed or intended to be extended or implemented by third parties anyway. So IMO going through a VOTE everytime one adds a new method to a script service is too constraining for little value.
My 2 cents Jerome
Totally agree.
Yes we can start brainstorming about it. It's a lot of work. We need to define precisely what we call SPI and what we call API and then define rules for SPI package name (probably needs "spi" in the package name or api needs to be put in an "api" package name), need to think about migration from what we have to the target, etc.
One other thing that bugs me is that a component that implements two roles will have two instances, and this makes it harder to have a class that implements both ScriptService and a specific role for that component.
Yes but that's not needed. The script service only needs to implement 1 component role, the interface doesn't have to be a role.
It is if you want to use it not just from scripts, but from Java as well. I'm talking mostly about utilities like XMLScriptService which don't expose an internal component to scripts, but provide their own functionality.
Then you should have a different component since ScriptService is… a script service and thus not meant to be used from Java…
I personally like the fact that a component can implement only one role. Makes a clean separation of concerns.
-Vincent
Thanks -Vincent
> Ludovic > > 2012/10/10 Marius Dumitru Florea <[email protected]> > >> On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> >> wrote: >>> Hi, >>> >>> I found an issue with the maven project to generate the javadocs for >>> SRD. Apparently all the internal packages are ignored. This is normal and good. We don't want to show these to the user.
Thanks -Vincent
>>> This is no necessarly a problem unless we want them in the javadocs. >>> Now there is a problem as some APIs are in internal, which does not >>> seem normal. >>> >>> This is the case of: >>> >>> org.xwiki.officeimporter.internal.script.OfficeImporterScriptService >>> >> org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService >> >>> org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService >> Most of our script services are internal. For the office module I need >> to create a single script service (hint=office) with 3 methods >> getImporter(), getManager() and getViewer(). >> >> Thanks, >> Marius >> >>> Until we find a solution i've reverted to the javadocs manually >>> generated (without the maven project). >>> >>> Ludovic
-- Sergiu Dumitriu http://purl.org/net/sergiu/ _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On 10/11/2012 11:18 AM, Thomas Mortagne wrote:
Actually ScriptServiceis not a good example since there are not supposed to have anything but calls to the actual component and convert/adapt/protect the data for scripting but there is perfectly valid use cases that are a pain to manage right now: invalidate some internal cache of a component based on events. For theses you would need to implement both the component main job and EventListener.
Yes, I forgot about that one, and that is indeed a much better example that I've hit several times.
On Thu, Oct 11, 2012 at 3:32 PM, Vincent Massol <[email protected]> wrote:
On Oct 11, 2012, at 3:03 PM, Sergiu Dumitriu <[email protected]> wrote:
On 10/10/2012 06:21 PM, Vincent Massol wrote:
On Oct 11, 2012, at 12:00 AM, Sergiu Dumitriu <[email protected]> wrote:
On 10/10/2012 12:03 PM, Jerome Velociter wrote:
On 10/10/2012 04:30 PM, Vincent Massol wrote: > Hi Ludovic, > > On Oct 10, 2012, at 3:39 PM, Ludovic Dubost <[email protected]> wrote: > >> Why would script services be internal ? They should have a stable API >> shouldn't they ? > Yes, I agree, each Script Service should define an interface and > implement it in addition to implementing ScriptService. > > We've been lazy and we should fix this as otherwise CLIRR won't let us > know when we break scripting APIs.
Wouln't it be good to start distinguish between API and SPI, and have a different set of CLIRR rules for each type ?
For instance, I don't see a big benefit in not allowing new methods in such script services interfaces. In my opinion those are not designed or intended to be extended or implemented by third parties anyway. So IMO going through a VOTE everytime one adds a new method to a script service is too constraining for little value.
My 2 cents Jerome
Totally agree.
Yes we can start brainstorming about it. It's a lot of work. We need to define precisely what we call SPI and what we call API and then define rules for SPI package name (probably needs "spi" in the package name or api needs to be put in an "api" package name), need to think about migration from what we have to the target, etc.
One other thing that bugs me is that a component that implements two roles will have two instances, and this makes it harder to have a class that implements both ScriptService and a specific role for that component.
Yes but that's not needed. The script service only needs to implement 1 component role, the interface doesn't have to be a role.
It is if you want to use it not just from scripts, but from Java as well. I'm talking mostly about utilities like XMLScriptService which don't expose an internal component to scripts, but provide their own functionality.
Then you should have a different component since ScriptService is… a script service and thus not meant to be used from Java…
I personally like the fact that a component can implement only one role. Makes a clean separation of concerns.
-Vincent
Thanks -Vincent
>> Ludovic >> >> 2012/10/10 Marius Dumitru Florea <[email protected]> >> >>> On Wed, Oct 10, 2012 at 3:28 PM, Ludovic Dubost <[email protected]> >>> wrote: >>>> Hi, >>>> >>>> I found an issue with the maven project to generate the javadocs for >>>> SRD. Apparently all the internal packages are ignored. > This is normal and good. We don't want to show these to the user. > > Thanks > -Vincent > >>>> This is no necessarly a problem unless we want them in the javadocs. >>>> Now there is a problem as some APIs are in internal, which does not >>>> seem normal. >>>> >>>> This is the case of: >>>> >>>> org.xwiki.officeimporter.internal.script.OfficeImporterScriptService >>>> >>> org.xwiki.officeimporter.internal.openoffice.script.OpenOfficeManagerScriptService >>> >>>> org.xwiki.office.viewer.internal.DefaultOfficeViewerScriptService >>> Most of our script services are internal. For the office module I need >>> to create a single script service (hint=office) with 3 methods >>> getImporter(), getManager() and getViewer(). >>> >>> Thanks, >>> Marius >>> >>>> Until we find a solution i've reverted to the javadocs manually >>>> generated (without the maven project). >>>> >>>> Ludovic
-- Sergiu Dumitriu http://purl.org/net/sergiu/
participants (6)
-
Jerome Velociter -
Ludovic Dubost -
Marius Dumitru Florea -
Sergiu Dumitriu -
Thomas Mortagne -
Vincent Massol