You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@openoffice.apache.org by Arrigo Marchiori <ar...@yahoo.it.INVALID> on 2021/10/14 17:08:25 UTC
API doc on web site [Was: Accessing the comment object (annotation)
in Draw/Impress via API]
Hello,
On Wed, Oct 13, 2021 at 12:10:52AM +0200, Marcus wrote:
> Am 12.10.21 um 22:06 schrieb Arrigo Marchiori:
> >
> > On Mon, Oct 11, 2021 at 04:53:56PM +0200, Czesław Wolański wrote:
> >
> > > Recently a user on the English forum inquired how one can change the font
> > > size in a comment box in Draw [1].
> > > He was given the obvious workaround tip and then the discussion started on
> > > how to access the comment object via API.
> > > Though the AOO's IDL reference says nothing in this regard, it turned out
> > > the annotation can be handled
> > > programmatically (at least in OpenOffice Basic).
> > >
> > > Hence my questions:
> > > 1. Is the API in terms of annotations' handling fully operational?
> > > 2. Should the relevant AOO's IDL reference be amended?
> > > see:
> > > https://www.openoffice.org/api/docs/common/ref/com/sun/star/office/module-ix.html
> >
> > I guess that the "API documentation" is extracted from autodoc or
> > something like that... how can we update it on our web site? Are there
> > any scripts or procedures?
> >
> > Thank you in advance for any pointers,
>
> the API doc is (somehow) part of the website. And what you are looking for
> is maybe here:
>
> https://github.com/apache/openoffice-org/blob/main/part2/content/api/docs/common/ref/com/sun/star/office/module-ix.html
Thank you! That is what I meant.
Those pages should be generated by Autodoc, for what I understand.
Are there any scripts that do this? Or any policies on how and when to
update the API documentation? For example, I would suggest that each
new release would be a good time to update the API.
Best regards,
--
Arrigo
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Posted by Jörg Schmidt <jo...@j-m-schmidt.de>.
> -----Original Message-----
> From: Arrigo Marchiori [mailto:ardovm@yahoo.it.INVALID]
> Sent: Monday, October 18, 2021 8:08 AM
> To: dev@openoffice.apache.org
> Subject: Re: API doc on web site [Was: Accessing the comment
> object (annotation) in Draw/Impress via API]
>
> Hello All,
>
> replying to myself as a correction.
>
> On Thu, Oct 14, 2021 at 07:08:25PM +0200, Arrigo Marchiori wrote:
>
> [...]
> > Those pages should be generated by Autodoc, for what I understand.
> >
> > Are there any scripts that do this? Or any policies on how
> and when to
> > update the API documentation? For example, I would suggest
> that each
> > new release would be a good time to update the API.
>
> I should have written "API documentation" instead of API. I apologize.
I assumed that 'API documentation' was meant, so all is well, no misunderstanding.
> I agree that changing the API is a ``big thing'', that we shall be
> very careful, and I understand Jörg's and Marcus' concern while
> reading my paragraph above!
>
> I suggest we update the _documentation_ whenever possible because
"whenever possible"?
-1
'whenever necessary'
+1
The difference between both things is a basic principle, e.g. in mechanical engineering (it is always worked as exactly as necessary, not as possible) as well as in programming, because one should not change any code (here documentation) if it is not necessary, because every change contains the risk of errors.
> IMHO
> that can be helpful for developers.
Well, I've been professionally developing macros and extensions for OpenOffice for close to 15 years and I caution against frivolously updating the API documentation via automated processes until we have proper QA.
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Marcus <ma...@wtnet.de>.
Am 18.10.21 um 08:07 schrieb Arrigo Marchiori:
>
> replying to myself as a correction.
>
> On Thu, Oct 14, 2021 at 07:08:25PM +0200, Arrigo Marchiori wrote:
>
> [...]
>> Those pages should be generated by Autodoc, for what I understand.
>>
>> Are there any scripts that do this? Or any policies on how and when to
>> update the API documentation? For example, I would suggest that each
>> new release would be a good time to update the API.
>
> I should have written "API documentation" instead of API. I apologize.
ah, that is changing the game. ;-)
> I agree that changing the API is a ``big thing'', that we shall be
> very careful, and I understand Jörg's and Marcus' concern while
> reading my paragraph above!
>
> I suggest we update the _documentation_ whenever possible because IMHO
> that can be helpful for developers.
The details can and should be discussed when it comes to updates. But in
general I agree.
> I hope I could clarify my proposal now.
Yes, thanks
Marcus
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Arrigo Marchiori <ar...@yahoo.it.INVALID>.
Hello All,
replying to myself as a correction.
On Thu, Oct 14, 2021 at 07:08:25PM +0200, Arrigo Marchiori wrote:
[...]
> Those pages should be generated by Autodoc, for what I understand.
>
> Are there any scripts that do this? Or any policies on how and when to
> update the API documentation? For example, I would suggest that each
> new release would be a good time to update the API.
I should have written "API documentation" instead of API. I apologize.
I agree that changing the API is a ``big thing'', that we shall be
very careful, and I understand Jörg's and Marcus' concern while
reading my paragraph above!
I suggest we update the _documentation_ whenever possible because IMHO
that can be helpful for developers.
I hope I could clarify my proposal now.
Best regards,
--
Arrigo
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Posted by Jörg Schmidt <jo...@j-m-schmidt.de>.
Hello Peter,
> -----Original Message-----
> From: Peter Kovacs [mailto:petko@apache.org]
> Sent: Sunday, October 17, 2021 11:18 PM
> To: dev@openoffice.apache.org
> Subject: Re: API doc on web site [Was: Accessing the comment
> object (annotation) in Draw/Impress via API]
> The API Documentation is extracted from the Code.
>
> For example the comment in
>
> http://opengrok.openoffice.org/xref/aoo41x/main/offapi/com/sun
> /star/modules.idl?r=d1766043#83
>
> does have an impact on the web page:
>
> https://www.openoffice.org/api/docs/common/ref/com/sun/star/of
> fice/module-ix.html
>
> I hope you see both documentations are linked. So when do we
> update the
> documentation on the web site?
>
> Currently we will never update the web site, and the danger
> is that if
> we change a comment in the documentation it will not end up
> on the website..
>
> So Arrigos Idea is to update with each release. This would keep the
> documentation on the web in sync with the latest Code
> released for this
> API Version (Which should roughly correspond with the major release).
>
> It makes sense to publish on the website which Code the
> extraction has
> been taken from and what Versions the Documentation relates to.
>
> On an API Change, QA and documentation Versions need to be
> discussed.
yes, exactly.
> But we can discuss this when we get near to a API Change. I
> think until
> then we have done some steps in respect of QA.
How do you come to this hope, so we can all see that there is no regulated QA for years? Basically there is no real QA since Raphael left the project.
That's just a description of the situation, because we lack enough volunteers to build up a really sufficient QA. But volunteers have to be motivated and for this we have to recognize performance and not admit people to the PMC according to personal preference (called alleged "merit"), but only according to performance.
For example, we should have discussed honestly and factually how it came to the release mikt the (so-called) 'Big Sur Bug', to improve our release procedures, that such gross errors no longer occur. But nothing happened.
'9 years as a top level project' ... well, I've been in the OO project for more than 16 years ...
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Posted by Jörg Schmidt <jo...@j-m-schmidt.de>.
> -----Original Message-----
> From: Peter Kovacs [mailto:petko@apache.org]
> Sent: Sunday, October 24, 2021 9:42 PM
> To: dev@openoffice.apache.org
> Subject: Re: API doc on web site [Was: Accessing the comment
> object (annotation) in Draw/Impress via API]
> > The question of what "compatible" actually means is by no
> means easy to answer.
> >
> > Example: Perhaps there is a property, method, etc. in the
> API that accidentally has a spelling mistake in its name (I
> recently had something like this in LO regarding a parameter
> of a Posgresql access) - on the one hand, one can then argue
> that a name correction that does not change the actual
> function would be compatible, but one can also argue that it
> is incompatible because only the old naming (which is
> possibly already used a lot in projects) no longer works.
>
> I define Incompatible on User API level if the API user has to change
> his work, as a result of changes in a release.
OK, but what helps and your (or my) definition? We need a definition that everyone recognises, especially the PMC because they have the power to decide on releases.
But I repeat myself: your statements about major, minor and micro releases, and that API changes should only be made in major releases, make sense and are recognised (I think by everyone). So why should we want to violate them?
greetings,
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Peter Kovacs <pe...@apache.org>.
On 24.10.21 20:57, Jörg Schmidt wrote:
>
>
>> -----Original Message-----
>> From: Peter Kovacs [mailto:petko@apache.org]
>> Sent: Sunday, October 24, 2021 2:19 PM
>> To: dev@openoffice.apache.org
>> Subject: Re: API doc on web site [Was: Accessing the comment
>> object (annotation) in Draw/Impress via API]
>>
>> Hi Jörg,
>>
>> Check:
>>
>>
>> Version Number Assignment (Apache OpenOffice internal)
>>
>>
>> Structure
>>
>> <major>.<minor>.<micro>
>>
>>
>> Explanation
>>
>> <major>: huge release with visible changes and new features including
>> incompatible API changes if necessary. Translation updates are most
>> often necessary to address the UI visible changes.
>>
>> <minor>: smaller improvements of features that don't need any
>> translation. And of course any kind of bug fixes.
>>
>> <micro>: only selected bug fixes and most often only critical
>> ones. This
>> includes any potential security issues.
>>
>> From: https://cwiki.apache.org/confluence/display/OOOUSERS/Releases
> Yes, agreed.
>
>> That is the current policy. So well as long as compatible we could
>> Change the API with a minor Release.
> I see no need and no justification for watering down clear rules/explanations.
>
> The question of what "compatible" actually means is by no means easy to answer.
>
> Example: Perhaps there is a property, method, etc. in the API that accidentally has a spelling mistake in its name (I recently had something like this in LO regarding a parameter of a Posgresql access) - on the one hand, one can then argue that a name correction that does not change the actual function would be compatible, but one can also argue that it is incompatible because only the old naming (which is possibly already used a lot in projects) no longer works.
I define Incompatible on User API level if the API user has to change
his work, as a result of changes in a release.
--
This is the Way! http://www.apache.org/theapacheway/index.html
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Posted by Jörg Schmidt <jo...@j-m-schmidt.de>.
> -----Original Message-----
> From: Peter Kovacs [mailto:petko@apache.org]
> Sent: Sunday, October 24, 2021 2:19 PM
> To: dev@openoffice.apache.org
> Subject: Re: API doc on web site [Was: Accessing the comment
> object (annotation) in Draw/Impress via API]
>
> Hi Jörg,
>
> Check:
>
>
> Version Number Assignment (Apache OpenOffice internal)
>
>
> Structure
>
> <major>.<minor>.<micro>
>
>
> Explanation
>
> <major>: huge release with visible changes and new features including
> incompatible API changes if necessary. Translation updates are most
> often necessary to address the UI visible changes.
>
> <minor>: smaller improvements of features that don't need any
> translation. And of course any kind of bug fixes.
>
> <micro>: only selected bug fixes and most often only critical
> ones. This
> includes any potential security issues.
>
> From: https://cwiki.apache.org/confluence/display/OOOUSERS/Releases
Yes, agreed.
> That is the current policy. So well as long as compatible we could
> Change the API with a minor Release.
I see no need and no justification for watering down clear rules/explanations.
The question of what "compatible" actually means is by no means easy to answer.
Example: Perhaps there is a property, method, etc. in the API that accidentally has a spelling mistake in its name (I recently had something like this in LO regarding a parameter of a Posgresql access) - on the one hand, one can then argue that a name correction that does not change the actual function would be compatible, but one can also argue that it is incompatible because only the old naming (which is possibly already used a lot in projects) no longer works.
greetings,
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Peter Kovacs <pe...@apache.org>.
Hi Jörg,
Check:
Version Number Assignment (Apache OpenOffice internal)
Structure
<major>.<minor>.<micro>
Explanation
<major>: huge release with visible changes and new features including
incompatible API changes if necessary. Translation updates are most
often necessary to address the UI visible changes.
<minor>: smaller improvements of features that don't need any
translation. And of course any kind of bug fixes.
<micro>: only selected bug fixes and most often only critical ones. This
includes any potential security issues.
From: https://cwiki.apache.org/confluence/display/OOOUSERS/Releases
That is the current policy. So well as long as compatible we could
Change the API with a minor Release. It seems I got the detail wrong.
All the best
Peter
On 19.10.21 15:30, Jörg Schmidt wrote:
> Hello Carl,
>
>> -----Original Message-----
>> From: Carl Marcum [mailto:cmarcum@apache.org]
>> Sent: Tuesday, October 19, 2021 1:13 PM
>> To:dev@openoffice.apache.org
>> Subject: Re: API doc on web site [Was: Accessing the comment
>> object (annotation) in Draw/Impress via API]
>
>>>> Actually we do provide updated documentation included in
>> the SDK with
>>>> each convenience binary release.
>>>> It can be found on Linux at
>>>> /opt/openoffice4/sdk/docs/common/ref/module-ix.html
>>>> if the SDK is installed.
>>>>
>>>> Knowing that we can't make API changes like adding or deprecating
>>>> methods or things like that in a minor version change,
>>> Is this a principle that _all_ those involved in releases
>> will also _reliably_ follow?
>>
>> It's up to us to inform new contributors who may make such a
>> mistake if
>> it were to happen.
> yes, but ...
>
> As far as I know, only the PMC has the right to decide about the release of a release - so will the PMC reliably support the mentioned principle (='API changes not in a minor release')?
> I would appreciate a clear "yes" or "no" on this.
>
> And please allow me to say that the current formal minor release of AOO is "4.1", so, respecting the implied principle, a change to the API is thus not allowed until version 5.0.0.
>
>
>
> greetings,
> Jörg
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:dev-unsubscribe@openoffice.apache.org
> For additional commands, e-mail:dev-help@openoffice.apache.org
>
--
This is the Way! http://www.apache.org/theapacheway/index.html
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Posted by Jörg Schmidt <jo...@j-m-schmidt.de>.
Hello Carl,
> -----Original Message-----
> From: Carl Marcum [mailto:cmarcum@apache.org]
> Sent: Tuesday, October 19, 2021 1:13 PM
> To: dev@openoffice.apache.org
> Subject: Re: API doc on web site [Was: Accessing the comment
> object (annotation) in Draw/Impress via API]
> >> Actually we do provide updated documentation included in
> the SDK with
> >> each convenience binary release.
> >> It can be found on Linux at
> >> /opt/openoffice4/sdk/docs/common/ref/module-ix.html
> >> if the SDK is installed.
> >>
> >> Knowing that we can't make API changes like adding or deprecating
> >> methods or things like that in a minor version change,
> > Is this a principle that _all_ those involved in releases
> will also _reliably_ follow?
>
> It's up to us to inform new contributors who may make such a
> mistake if
> it were to happen.
yes, but ...
As far as I know, only the PMC has the right to decide about the release of a release - so will the PMC reliably support the mentioned principle (='API changes not in a minor release')?
I would appreciate a clear "yes" or "no" on this.
And please allow me to say that the current formal minor release of AOO is "4.1", so, respecting the implied principle, a change to the API is thus not allowed until version 5.0.0.
greetings,
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Carl Marcum <cm...@apache.org>.
Hi Jörg,
On 10/19/21 4:26 AM, Jörg Schmidt wrote:
>
>
>> -----Original Message-----
>> From: Carl Marcum [mailto:cmarcum@apache.org]
>> Sent: Tuesday, October 19, 2021 3:59 AM
>> To: dev@openoffice.apache.org
>> Subject: Re: API doc on web site [Was: Accessing the comment
>> object (annotation) in Draw/Impress via API]
>>
>> Hi All,
>>
>> On 10/17/21 5:17 PM, Peter Kovacs wrote:
>>> Hi Jörg,
>>>
>>> On 17.10.21 19:48, Jörg Schmidt wrote:
>>>> Hello Peter,
>>>>
>>>>> -----Original Message-----
>>>>> From: Peter Kovacs [mailto:petko@apache.org]
>>>>> Sent: Sunday, October 17, 2021 11:27 AM
>>>>> To: dev@openoffice.apache.org
>>>>> Subject: Re: API doc on web site [Was: Accessing the comment
>>>>> object (annotation) in Draw/Impress via API]
>>>>>
>>>>> Hi Jörg,
>>>>>
>>>>>
>>>>> I am not sure what you refer to.
>>>> I refer to the fact that changes in the API documentation
>> are marked
>>>> in time (the typical entry is "since ..."), so that the API
>>>> documentation can be used in practice for all program versions.
>>> I think we are on the same page if we want to change the API, but I
>>> think this is not the topic.
>>>>> The documentation has no
>>>>> influence on
>>>>> backward compatibility.
>>>> right.
>>>>
>>>> What I am referring to is only that we should not make
>> changes if the
>>>> QA is not 100% guaranteed. And what I currently experience is that
>>>> there is a tiny(!) problem in the API documentation, but
>> immediately
>>>> demanded now to regularly renew the documentation routinely.
>>> Again this is relevant if we change the API itself.
>>>> Explain to me bitterly where there are at all changes in
>> the API that
>>>> would make it necessary to update the documentation inflationary
>>>> frequently?
>>>> I follow every release carefully, only from API changes I have not
>>>> noticed for years.
>>> The API Documentation is extracted from the Code.
>>>
>>> For example the comment in
>>>
>>>
>> http://opengrok.openoffice.org/xref/aoo41x/main/offapi/com/sun
>> /star/modules.idl?r=d1766043#83
>>>
>>> does have an impact on the web page:
>>>
>>>
>> https://www.openoffice.org/api/docs/common/ref/com/sun/star/of
>> fice/module-ix.html
>>>
>>> I hope you see both documentations are linked. So when do we update
>>> the documentation on the web site?
>>>
>>> Currently we will never update the web site, and the danger
>> is that if
>>> we change a comment in the documentation it will not end up on the
>>> website..
>>>
>>> So Arrigos Idea is to update with each release. This would keep the
>>> documentation on the web in sync with the latest Code released for
>>> this API Version (Which should roughly correspond with the major
>>> release).
>>>
>>> It makes sense to publish on the website which Code the
>> extraction has
>>> been taken from and what Versions the Documentation relates to.
>>>
>>> On an API Change, QA and documentation Versions need to be
>> discussed.
>>> But we can discuss this when we get near to a API Change. I think
>>> until then we have done some steps in respect of QA.
>>>
>>> Carl is working on improvements, and I would like to try if we can
>>> establish a UI check with UI Path or similar tool.
>>>
>>> All the best
>>>
>>> Peter
>>>
>>>
>> Actually we do provide updated documentation included in the SDK with
>> each convenience binary release.
>> It can be found on Linux at
>> /opt/openoffice4/sdk/docs/common/ref/module-ix.html
>> if the SDK is installed.
>>
>> Knowing that we can't make API changes like adding or deprecating
>> methods or things like that in a minor version change,
> Is this a principle that _all_ those involved in releases will also _reliably_ follow?
It's up to us to inform new contributors who may make such a mistake if
it were to happen.
>
>
>
> On the whole question of API and documentation, I would like to make a general appeal to all of us:
>
> The fact that OpenOffice could not be displaced by LibreOffice is largely due to the good quality of OO.
> We must do everything we can to preserve this quality and not compromise in this regard. In this context, we must also be ready to examine, critically discuss and improve our activities again and again.
I very much agree.
Best regards,
Carl
>
>
>
> Jörg
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Posted by Jörg Schmidt <jo...@j-m-schmidt.de>.
> -----Original Message-----
> From: Carl Marcum [mailto:cmarcum@apache.org]
> Sent: Tuesday, October 19, 2021 3:59 AM
> To: dev@openoffice.apache.org
> Subject: Re: API doc on web site [Was: Accessing the comment
> object (annotation) in Draw/Impress via API]
>
> Hi All,
>
> On 10/17/21 5:17 PM, Peter Kovacs wrote:
> > Hi Jörg,
> >
> > On 17.10.21 19:48, Jörg Schmidt wrote:
> >> Hello Peter,
> >>
> >>> -----Original Message-----
> >>> From: Peter Kovacs [mailto:petko@apache.org]
> >>> Sent: Sunday, October 17, 2021 11:27 AM
> >>> To: dev@openoffice.apache.org
> >>> Subject: Re: API doc on web site [Was: Accessing the comment
> >>> object (annotation) in Draw/Impress via API]
> >>>
> >>> Hi Jörg,
> >>>
> >>>
> >>> I am not sure what you refer to.
> >> I refer to the fact that changes in the API documentation
> are marked
> >> in time (the typical entry is "since ..."), so that the API
> >> documentation can be used in practice for all program versions.
> > I think we are on the same page if we want to change the API, but I
> > think this is not the topic.
> >>> The documentation has no
> >>> influence on
> >>> backward compatibility.
> >> right.
> >>
> >> What I am referring to is only that we should not make
> changes if the
> >> QA is not 100% guaranteed. And what I currently experience is that
> >> there is a tiny(!) problem in the API documentation, but
> immediately
> >> demanded now to regularly renew the documentation routinely.
> > Again this is relevant if we change the API itself.
> >> Explain to me bitterly where there are at all changes in
> the API that
> >> would make it necessary to update the documentation inflationary
> >> frequently?
> >> I follow every release carefully, only from API changes I have not
> >> noticed for years.
> >
> > The API Documentation is extracted from the Code.
> >
> > For example the comment in
> >
> >
> http://opengrok.openoffice.org/xref/aoo41x/main/offapi/com/sun
> /star/modules.idl?r=d1766043#83
> >
> >
> > does have an impact on the web page:
> >
> >
> https://www.openoffice.org/api/docs/common/ref/com/sun/star/of
> fice/module-ix.html
> >
> >
> > I hope you see both documentations are linked. So when do we update
> > the documentation on the web site?
> >
> > Currently we will never update the web site, and the danger
> is that if
> > we change a comment in the documentation it will not end up on the
> > website..
> >
> > So Arrigos Idea is to update with each release. This would keep the
> > documentation on the web in sync with the latest Code released for
> > this API Version (Which should roughly correspond with the major
> > release).
> >
> > It makes sense to publish on the website which Code the
> extraction has
> > been taken from and what Versions the Documentation relates to.
> >
> > On an API Change, QA and documentation Versions need to be
> discussed.
> > But we can discuss this when we get near to a API Change. I think
> > until then we have done some steps in respect of QA.
> >
> > Carl is working on improvements, and I would like to try if we can
> > establish a UI check with UI Path or similar tool.
> >
> > All the best
> >
> > Peter
> >
> >
>
> Actually we do provide updated documentation included in the SDK with
> each convenience binary release.
> It can be found on Linux at
> /opt/openoffice4/sdk/docs/common/ref/module-ix.html
> if the SDK is installed.
>
> Knowing that we can't make API changes like adding or deprecating
> methods or things like that in a minor version change,
Is this a principle that _all_ those involved in releases will also _reliably_ follow?
On the whole question of API and documentation, I would like to make a general appeal to all of us:
The fact that OpenOffice could not be displaced by LibreOffice is largely due to the good quality of OO.
We must do everything we can to preserve this quality and not compromise in this regard. In this context, we must also be ready to examine, critically discuss and improve our activities again and again.
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Carl Marcum <cm...@apache.org>.
Hi All,
On 10/17/21 5:17 PM, Peter Kovacs wrote:
> Hi Jörg,
>
> On 17.10.21 19:48, Jörg Schmidt wrote:
>> Hello Peter,
>>
>>> -----Original Message-----
>>> From: Peter Kovacs [mailto:petko@apache.org]
>>> Sent: Sunday, October 17, 2021 11:27 AM
>>> To: dev@openoffice.apache.org
>>> Subject: Re: API doc on web site [Was: Accessing the comment
>>> object (annotation) in Draw/Impress via API]
>>>
>>> Hi Jörg,
>>>
>>>
>>> I am not sure what you refer to.
>> I refer to the fact that changes in the API documentation are marked
>> in time (the typical entry is "since ..."), so that the API
>> documentation can be used in practice for all program versions.
> I think we are on the same page if we want to change the API, but I
> think this is not the topic.
>>> The documentation has no
>>> influence on
>>> backward compatibility.
>> right.
>>
>> What I am referring to is only that we should not make changes if the
>> QA is not 100% guaranteed. And what I currently experience is that
>> there is a tiny(!) problem in the API documentation, but immediately
>> demanded now to regularly renew the documentation routinely.
> Again this is relevant if we change the API itself.
>> Explain to me bitterly where there are at all changes in the API that
>> would make it necessary to update the documentation inflationary
>> frequently?
>> I follow every release carefully, only from API changes I have not
>> noticed for years.
>
> The API Documentation is extracted from the Code.
>
> For example the comment in
>
> http://opengrok.openoffice.org/xref/aoo41x/main/offapi/com/sun/star/modules.idl?r=d1766043#83
>
>
> does have an impact on the web page:
>
> https://www.openoffice.org/api/docs/common/ref/com/sun/star/office/module-ix.html
>
>
> I hope you see both documentations are linked. So when do we update
> the documentation on the web site?
>
> Currently we will never update the web site, and the danger is that if
> we change a comment in the documentation it will not end up on the
> website..
>
> So Arrigos Idea is to update with each release. This would keep the
> documentation on the web in sync with the latest Code released for
> this API Version (Which should roughly correspond with the major
> release).
>
> It makes sense to publish on the website which Code the extraction has
> been taken from and what Versions the Documentation relates to.
>
> On an API Change, QA and documentation Versions need to be discussed.
> But we can discuss this when we get near to a API Change. I think
> until then we have done some steps in respect of QA.
>
> Carl is working on improvements, and I would like to try if we can
> establish a UI check with UI Path or similar tool.
>
> All the best
>
> Peter
>
>
Actually we do provide updated documentation included in the SDK with
each convenience binary release.
It can be found on Linux at
/opt/openoffice4/sdk/docs/common/ref/module-ix.html
if the SDK is installed.
Knowing that we can't make API changes like adding or deprecating
methods or things like that in a minor version change, any updates I
imagine would be to improve documentation of current API.
I don't see a problem with that and I think there is a lot of room for
improvement especially around examples and more description.
I have more concern around the website and SDK being out of sync if in
fact documentation changes have been made which I don't know whether
that's the case or not.
Maybe that's something we can look at making sure the website has the
latest copy.
Slightly off-topic is that the Java documentation doesn't include all of
the juh, jurt, and ridl classes like it could.
I've been able to generate them and packed into and archive during a
build but I haven't solved getting them into the packaging part.
Best regards,
Carl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Peter Kovacs <pe...@apache.org>.
Hi Jörg,
On 17.10.21 19:48, Jörg Schmidt wrote:
> Hello Peter,
>
>> -----Original Message-----
>> From: Peter Kovacs [mailto:petko@apache.org]
>> Sent: Sunday, October 17, 2021 11:27 AM
>> To: dev@openoffice.apache.org
>> Subject: Re: API doc on web site [Was: Accessing the comment
>> object (annotation) in Draw/Impress via API]
>>
>> Hi Jörg,
>>
>>
>> I am not sure what you refer to.
> I refer to the fact that changes in the API documentation are marked in time (the typical entry is "since ..."), so that the API documentation can be used in practice for all program versions.
I think we are on the same page if we want to change the API, but I
think this is not the topic.
>> The documentation has no
>> influence on
>> backward compatibility.
> right.
>
> What I am referring to is only that we should not make changes if the QA is not 100% guaranteed. And what I currently experience is that there is a tiny(!) problem in the API documentation, but immediately demanded now to regularly renew the documentation routinely.
Again this is relevant if we change the API itself.
> Explain to me bitterly where there are at all changes in the API that would make it necessary to update the documentation inflationary frequently?
> I follow every release carefully, only from API changes I have not noticed for years.
The API Documentation is extracted from the Code.
For example the comment in
http://opengrok.openoffice.org/xref/aoo41x/main/offapi/com/sun/star/modules.idl?r=d1766043#83
does have an impact on the web page:
https://www.openoffice.org/api/docs/common/ref/com/sun/star/office/module-ix.html
I hope you see both documentations are linked. So when do we update the
documentation on the web site?
Currently we will never update the web site, and the danger is that if
we change a comment in the documentation it will not end up on the website..
So Arrigos Idea is to update with each release. This would keep the
documentation on the web in sync with the latest Code released for this
API Version (Which should roughly correspond with the major release).
It makes sense to publish on the website which Code the extraction has
been taken from and what Versions the Documentation relates to.
On an API Change, QA and documentation Versions need to be discussed.
But we can discuss this when we get near to a API Change. I think until
then we have done some steps in respect of QA.
Carl is working on improvements, and I would like to try if we can
establish a UI check with UI Path or similar tool.
All the best
Peter
--
This is the Way! http://www.apache.org/theapacheway/index.html
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Posted by Jörg Schmidt <jo...@j-m-schmidt.de>.
Hello Peter,
> -----Original Message-----
> From: Peter Kovacs [mailto:petko@apache.org]
> Sent: Sunday, October 17, 2021 11:27 AM
> To: dev@openoffice.apache.org
> Subject: Re: API doc on web site [Was: Accessing the comment
> object (annotation) in Draw/Impress via API]
>
> Hi Jörg,
>
>
> I am not sure what you refer to.
I refer to the fact that changes in the API documentation are marked in time (the typical entry is "since ..."), so that the API documentation can be used in practice for all program versions.
> The documentation has no
> influence on
> backward compatibility.
right.
What I am referring to is only that we should not make changes if the QA is not 100% guaranteed. And what I currently experience is that there is a tiny(!) problem in the API documentation, but immediately demanded now to regularly renew the documentation routinely.
Explain to me bitterly where there are at all changes in the API that would make it necessary to update the documentation inflationary frequently?
I follow every release carefully, only from API changes I have not noticed for years.
> It would be beneficial if we update the documentation
> with each release,
> allowing a process that the documentation improves.
And where is this process?
What I see is that we don't even have a regulated QA for the program. Why do you want to make more work for which quality assurance never has the time?
> I would not see documentation update as a blocker to a release thought.
Neither do I in the least, but that's not the point, it's the quality assurance of the API documentation.
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Peter Kovacs <pe...@apache.org>.
Hi Jörg,
I am not sure what you refer to. The documentation has no influence on
backward compatibility.
According to current rules for Version numbers we must bump the first
digit if we do an API change.
So for Version 5 we must provide a Documentation a Version 4
Documentation and a Version 5 Documentation.
I think even if Version 5 is backward compatible with Version 4, the
documentation should be per Main Version.
I am fighting that we stick to the rule. (Actually I whish we only
change the first Digit if we have an API change. Which is a clear signal
to anyone what he has to look out for.
Current rules have a loophole to bumb for a majore release for features.
Which I do not see the benefit in. But this is maybe a different discussion)
It would be beneficial if we update the documentation with each release,
allowing a process that the documentation improves.
I think that means at current release speed we update API Documentation
once / twice a year. Which should not be to much effort?
I would not see documentation update as a blocker to a release thought.
Maybe even not part on the Release itself. But I think it is smart
to have both process in sync.
I think Arrigos Idea is a good one.
All the best
Peter
On 15.10.21 10:15, Jörg Schmidt wrote:
>> -----Original Message-----
>> From: Arrigo Marchiori [mailto:ardovm@yahoo.it.INVALID]
>> Sent: Thursday, October 14, 2021 7:08 PM
>> To: dev@openoffice.apache.org
>> Subject: API doc on web site [Was: Accessing the comment
>> object (annotation) in Draw/Impress via API]
>>> the API doc is (somehow) part of the website. And what you
>> are looking for
>>> is maybe here:
>>>
>>>
>> https://github.com/apache/openoffice-org/blob/main/part2/conte
>> nt/api/docs/common/ref/com/sun/star/office/module-ix.html
>>
>> Thank you! That is what I meant.
>>
>> Those pages should be generated by Autodoc, for what I understand.
>>
>> Are there any scripts that do this? Or any policies on how and when to
>> update the API documentation? For example, I would suggest that each
>> new release would be a good time to update the API.
> -1 (for the moment)
>
> this is only a good idea if there was a way to make backward compatibility, because information is needed for all OO versions, not only for the current version
>
> please understand me correctly:
> it's not about not changing anything, it's about not changing a whole procedure without careful(!) examination just because there is an incorrect entry
>
>
> Jörg
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
--
This is the Way! http://www.apache.org/theapacheway/index.html
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object
(annotation) in Draw/Impress via API]
Posted by Marcus <ma...@wtnet.de>.
Am 15.10.21 um 10:15 schrieb Jörg Schmidt:
>> -----Original Message-----
>> From: Arrigo Marchiori [mailto:ardovm@yahoo.it.INVALID]
>> Sent: Thursday, October 14, 2021 7:08 PM
>> To: dev@openoffice.apache.org
>> Subject: API doc on web site [Was: Accessing the comment
>> object (annotation) in Draw/Impress via API]
>>> the API doc is (somehow) part of the website. And what you
>> are looking for
>>> is maybe here:
>>>
>>>
>> https://github.com/apache/openoffice-org/blob/main/part2/conte
>> nt/api/docs/common/ref/com/sun/star/office/module-ix.html
>>
>> Thank you! That is what I meant.
>>
>> Those pages should be generated by Autodoc, for what I understand.
>>
>> Are there any scripts that do this? Or any policies on how and when to
>> update the API documentation? For example, I would suggest that each
>> new release would be a good time to update the API.
please not really for each release. We should provide our users with a
stable API at least for the 4.1.x release branch. Maybe also for 4.x.y.
Marcus
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Posted by Jörg Schmidt <jo...@j-m-schmidt.de>.
> -----Original Message-----
> From: Arrigo Marchiori [mailto:ardovm@yahoo.it.INVALID]
> Sent: Thursday, October 14, 2021 7:08 PM
> To: dev@openoffice.apache.org
> Subject: API doc on web site [Was: Accessing the comment
> object (annotation) in Draw/Impress via API]
> > the API doc is (somehow) part of the website. And what you
> are looking for
> > is maybe here:
> >
> >
> https://github.com/apache/openoffice-org/blob/main/part2/conte
> nt/api/docs/common/ref/com/sun/star/office/module-ix.html
>
> Thank you! That is what I meant.
>
> Those pages should be generated by Autodoc, for what I understand.
>
> Are there any scripts that do this? Or any policies on how and when to
> update the API documentation? For example, I would suggest that each
> new release would be a good time to update the API.
-1 (for the moment)
this is only a good idea if there was a way to make backward compatibility, because information is needed for all OO versions, not only for the current version
please understand me correctly:
it's not about not changing anything, it's about not changing a whole procedure without careful(!) examination just because there is an incorrect entry
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org