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/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-unsubscr...@openoffice.apache.org
For additional commands, e-mail: dev-h...@openoffice.apache.org
