Hi Jörg,
On 10/19/21 4:26 AM, Jörg Schmidt wrote:
-----Original Message-----
From: Carl Marcum [mailto:cmar...@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:pe...@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-unsubscr...@openoffice.apache.org
For additional commands, e-mail: dev-h...@openoffice.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org
For additional commands, e-mail: dev-h...@openoffice.apache.org
