Re: Updating the documentation in the IDL files?

[Noel Grandin]

On 2012-04-12 11:23, Michael Meeks wrote:
Trying to infer that structure from the interface documentation is (I 
suspect) an extremely irritating way to work out how to do what is 
needed :-) 


Perhaps we just need some links to the relevant docs on the libreoffice 
wiki from places like

   odk/README
   offapi/README



Disclaimer: http://www.peralex.com/disclaimer.html


___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Updating the documentation in the IDL files?

[Michael Meeks]

On Wed, 2012-04-11 at 20:52 +0300, Tor Lillqvist wrote:
> > But if you have anything more specific about com/sun/star/lang I could 
> > probably have a
> > look there.
> 
> Well, starting with XComponent.idl, I don't see any high-level
> description what a "component" *is* ;)

I guess there is again the tension between generic interfaces, and a
useful taxonomy of the objects (with their interfaces) that LibreOffice
actually provides.

I imagine there should be a good overview / drawing of the actual
objects that the suite provides, with the interfaces they implement as
an incidental extra alongside that :-)

Trying to infer that structure from the interface documentation is (I
suspect) an extremely irritating way to work out how to do what is
needed :-)

ATB,

Michael.

-- 
michael.me...@suse.com  <><, Pseudo Engineer, itinerant idiot

___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Updating the documentation in the IDL files?

[Stephan Bergmann]

On 04/11/2012 09:27 PM, Tor Lillqvist wrote:

OK... Those indeed help. So XComponent is an interface to be added to
types that might have circular references?


Yes, see . 
(And, of course, the interface is badly named.  Something like 
"XDisposable" might have been a better choice.)



When for instance Frame.idl talks about "components", does it mean the
XComponent kind of component, or "component" in some other meaning?


The problem with "component" is that it is such a nice, generic term...

Stephan
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Updating the documentation in the IDL files?

[Tor Lillqvist]

> When for instance Frame.idl talks about "components", does it mean the
> XComponent kind of component, or "component" in some other meaning?

And then again we have XComponentLoader, which says "loads a component
specified by an URL into the specified new or existing frame". But
that "component" apparently means "document", more or less?

And of course, yeah, the XComponent kind of component is in udkapi, in
com.sun.star.lang, while that other kind of component is in offapi, in
com.sun.star.frame, so I guess they are two unrelated concepts that
just happen to have the same terminology...

--tml
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Updating the documentation in the IDL files?

[Tor Lillqvist]

> http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ProUNO/The_XComponent_Interface

> http://api.libreoffice.org/docs/common/ref/com/sun/star/lang/XComponent.html

OK... Those indeed help. So XComponent is an interface to be added to
types that might have circular references?

When for instance Frame.idl talks about "components", does it mean the
XComponent kind of component, or "component" in some other meaning?

--tml
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Updating the documentation in the IDL files?

[Michael Stahl]

On 11/04/12 19:52, Tor Lillqvist wrote:
>> But if you have anything more specific about com/sun/star/lang I could 
>> probably have a
>> look there.
> 
> Well, starting with XComponent.idl, I don't see any high-level
> description what a "component" *is* ;)

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/ProUNO/The_XComponent_Interface

> Or am I expecting too much from the documentation in the IDL files
> (and generated from that), is it so that the reader is expected to
> have grokked some other, more prose style (not doc-comment -style)
> documentation first before reading the IDL comments?

generally the DevGuide has the high-level documentation; the odk build
also inserts various references to the DevGuide into the generated HTML
documentation (which is one reason why autodoc is still required), for
example take a look at:

http://api.libreoffice.org/docs/common/ref/com/sun/star/lang/XComponent.html

___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Updating the documentation in the IDL files?

[Tor Lillqvist]

> But if you have anything more specific about com/sun/star/lang I could 
> probably have a
> look there.

Well, starting with XComponent.idl, I don't see any high-level
description what a "component" *is* ;)

Or am I expecting too much from the documentation in the IDL files
(and generated from that), is it so that the reader is expected to
have grokked some other, more prose style (not doc-comment -style)
documentation first before reading the IDL comments?

--tml
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice

Re: Updating the documentation in the IDL files?

[Stephan Bergmann]

On 04/11/2012 03:31 PM, Tor Lillqvist wrote:

It would be nice if somebody with enough insight in these matters
would spend some hours on updating some of the documentation in the
"core" IDL files of the UNO ecosystem, like the most important ones in
com/sun/star/lang and com/sun/star/frame .

That is, assuming I am correct in thinking that lots of the
documentation in these is written from the point of view of a (now
non-existent) StarSomething desktop environment, with "the" office
being just one part of such a desktop environment.

This would IMHO help a lot in understanding what the concepts mean...
describing in real-world terms what a "Desktop" and "Frame" is etc.


I have no real idea about the com/sun/star/frame stuff either.  But if 
you have anything more specific about com/sun/star/lang I could probably 
have a look there.


Stephan
___
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice