From f9a606ecd39f59364e9b0a88d38775f07a31fb82 Mon Sep 17 00:00:00 2001 From: Michael Stahl Date: Thu, 30 May 2013 13:28:29 +0200 Subject: *api: tweak docs Change-Id: I20878a3977fe7b3ab7e733a7bc0d704fb5835009 --- udkapi/com/sun/star/io/DataInputStream.idl | 2 +- udkapi/com/sun/star/io/FilePermission.idl | 4 ++-- udkapi/com/sun/star/io/XInputStream.idl | 17 ++++++++++------- udkapi/com/sun/star/io/XPersistObject.idl | 10 +++++----- udkapi/com/sun/star/lang/XComponent.idl | 23 +++++++++-------------- udkapi/com/sun/star/lang/XMultiServiceFactory.idl | 16 +++++++--------- udkapi/com/sun/star/lang/XServiceInfo.idl | 2 +- udkapi/com/sun/star/lang/XTypeProvider.idl | 8 +++++--- udkapi/com/sun/star/uno/XCurrentContext.idl | 2 +- 9 files changed, 41 insertions(+), 43 deletions(-) (limited to 'udkapi/com') diff --git a/udkapi/com/sun/star/io/DataInputStream.idl b/udkapi/com/sun/star/io/DataInputStream.idl index 81b590d4f22a..923ce61d541e 100644 --- a/udkapi/com/sun/star/io/DataInputStream.idl +++ b/udkapi/com/sun/star/io/DataInputStream.idl @@ -47,7 +47,7 @@ published service DataInputStream */ interface com::sun::star::io::XActiveDataSink; - /** Allows to chain the DataInputStream, so that + /** Allows to chain the DataInputStream. */ interface com::sun::star::io::XConnectable; diff --git a/udkapi/com/sun/star/io/FilePermission.idl b/udkapi/com/sun/star/io/FilePermission.idl index 2b498a01f597..d23d90a38bee 100644 --- a/udkapi/com/sun/star/io/FilePermission.idl +++ b/udkapi/com/sun/star/io/FilePermission.idl @@ -29,7 +29,7 @@ module com { module sun { module star { module io { directories contained in that directory. A path that ends with "/-" indicates (recursively) all files and subdirectories contained in that directory. A file url string consisting of the special token - "<<ALL FILES>>" matches any file. + "<>" matches any file.
Note: A file url string consisting of a single "*" indicates all the files in the current directory, while a string consisting of a single "-" indicates @@ -52,7 +52,7 @@ module com { module sun { module star { module io { @attention Be careful when granting FilePermissions. Think about the implications of granting read and especially write access to various files and directories. - The "<<ALL FILES>>" permission with write action is + The "<>" permission with write action is especially dangerous. This grants permission to write to the entire file system. @since OOo 1.1.2 diff --git a/udkapi/com/sun/star/io/XInputStream.idl b/udkapi/com/sun/star/io/XInputStream.idl index 9e65585914e5..2a8d433868b6 100644 --- a/udkapi/com/sun/star/io/XInputStream.idl +++ b/udkapi/com/sun/star/io/XInputStream.idl @@ -43,11 +43,11 @@ published interface XInputStream: com::sun::star::uno::XInterface and the return value indicates that EOF has been reached. This means that the method blocks until the specified number of bytes are available or the EOF is reached.

- @param aData + + @param aData after the call, the byte sequence contains the requested number of bytes (or less as a sign of EOF). - -

+
C++ only : Note that for unbridged (e.g., in-process) calls, using the same sequence for repetive readBytes()-calls can bear a performance advantage. The callee can put the data @@ -63,13 +63,14 @@ published interface XInputStream: com::sun::star::uno::XInterface

  • the call is not bridged (e.g., betweeen different compilers or different processes ). - +
    If the same 'optimized' code runs against an interface in a different process, there is an unnecessary memory allocation/deallocation (the out parameter is of course NOT transported over the connection), but this should be negligible compared to a synchron call. + @param nBytesToRead - the total number of bytes to read + the total number of bytes to read */ long readBytes( [out] sequence aData, [in] long nBytesToRead ) @@ -87,6 +88,7 @@ published interface XInputStream: com::sun::star::uno::XInterface returns 0 and the corresponding byte sequence is empty. Otherwise, after the call, aData contains the available, but no more than nMaxBytesToRead, bytes. + @param aData contains the data read from the stream. @param nMaxBytesToRead The maximum number of bytes to be read from this stream during the call. @@ -102,8 +104,9 @@ published interface XInputStream: com::sun::star::uno::XInterface

    It is up to the implementation whether this method is blocking the thread or not.

    - @param nBytesToSkip - number of bytes to skip + + @param nBytesToSkip + number of bytes to skip */ void skipBytes( [in] long nBytesToSkip ) raises( com::sun::star::io::NotConnectedException, diff --git a/udkapi/com/sun/star/io/XPersistObject.idl b/udkapi/com/sun/star/io/XPersistObject.idl index 2f6c8e06dc3b..3f39896edcab 100644 --- a/udkapi/com/sun/star/io/XPersistObject.idl +++ b/udkapi/com/sun/star/io/XPersistObject.idl @@ -56,14 +56,14 @@ published interface XPersistObject: com::sun::star::uno::XInterface /** gives the service name of the object - @returns - the service name that specifies the behavior and the - persistent data format of this implementation. -

    This name is used to create such an object by a factory during deserialization.

    - @see com::sun::star::lang::XServiceInfo::getAvailableServiceNames + @returns + the service name that specifies the behavior and the + persistent data format of this implementation. + + @see com::sun::star::lang::XMultiComponentFactory::getAvailableServiceNames() */ string getServiceName(); diff --git a/udkapi/com/sun/star/lang/XComponent.idl b/udkapi/com/sun/star/lang/XComponent.idl index 7f03ba6f39ec..4711bea0c16e 100644 --- a/udkapi/com/sun/star/lang/XComponent.idl +++ b/udkapi/com/sun/star/lang/XComponent.idl @@ -63,7 +63,7 @@ published interface XComponent: com::sun::star::uno::XInterface Often the object can't fulfill its specification anymore, in this case it must throw the DisposedException (which is derived from com::sun::star::uno::RuntimeException) - when it gets called.

    + when it gets called.

    For some objects no real owner can be identified, thus it can be disposed from multiple reference holders. In this case @@ -80,15 +80,12 @@ published interface XComponent: com::sun::star::uno::XInterface

    It is suggested to allow multiple registration of the same listener, thus for each time a listener is added, it has to be removed.

    -

    If this com::sun::star::lang::XComponent is - already disposed when - com::sun::star::lang::XComponent::addEventListener() - is called, the call will not fail - with a com::sun::star::lang::DisposedException, but - the caller will be notified via the - com::sun::star::lang::XEventListener::disposing() +

    If this XComponent is already disposed when + XComponent::addEventListener() is called, the call will not fail + with a DisposedException, but the caller will be notified via the + XEventListener::disposing() callback. This callback can occur synchronously within the - com::sun::star::lang::XComponent::addEventListener() call.

    + addEventListener() call.

    @see XComponent::removeEventListener */ @@ -101,11 +98,9 @@ published interface XComponent: com::sun::star::uno::XInterface

    It is suggested to allow multiple registration of the same listener, thus for each time a listener is added, it has to be removed. -

    If this com::sun::star::lang::XComponent is - already disposed when - com::sun::star::lang::XComponent::removeEventListener() - is called, the call will not - fail with a com::sun::star::lang::DisposedException, +

    If this XComponent is already disposed when + XComponent::removeEventListener() is called, the call will not + fail with a DisposedException, but will rather be ignored silently.

    @see XComponent::addEventListener diff --git a/udkapi/com/sun/star/lang/XMultiServiceFactory.idl b/udkapi/com/sun/star/lang/XMultiServiceFactory.idl index c36b4c9d5f3e..31b5725d9896 100644 --- a/udkapi/com/sun/star/lang/XMultiServiceFactory.idl +++ b/udkapi/com/sun/star/lang/XMultiServiceFactory.idl @@ -28,15 +28,13 @@ module com { module sun { module star { module lang { -/** Factories support this interface creating instances giving a name, - e.g. a service name. - -

    - Note: - Although this interface deals with the notion of "services", this is not - generally be meant. In general this interface can be used for all kinds - of factories for all kinds of instances, indeed not only UNO services. -

    +/** Allows creating instances specified by a string name. + + @note + Although this interface deals with the notion of "services", it is + not restricted to services but is more general. + This interface can be used for all kinds + of factories for all kinds of instances, not only UNO services. */ published interface XMultiServiceFactory: com::sun::star::uno::XInterface { diff --git a/udkapi/com/sun/star/lang/XServiceInfo.idl b/udkapi/com/sun/star/lang/XServiceInfo.idl index 4ff9ffb63add..ff9603c25b96 100644 --- a/udkapi/com/sun/star/lang/XServiceInfo.idl +++ b/udkapi/com/sun/star/lang/XServiceInfo.idl @@ -26,7 +26,7 @@ module com { module sun { module star { module lang { -/** Provides information regarding the implementation, i.e. which services +/** Provides information regarding the implementation: which services are implemented and the name of the implementation. */ published interface XServiceInfo: com::sun::star::uno::XInterface diff --git a/udkapi/com/sun/star/lang/XTypeProvider.idl b/udkapi/com/sun/star/lang/XTypeProvider.idl index d429ba08f9fa..a396472bb0e9 100644 --- a/udkapi/com/sun/star/lang/XTypeProvider.idl +++ b/udkapi/com/sun/star/lang/XTypeProvider.idl @@ -35,7 +35,8 @@ published interface XTypeProvider: com::sun::star::uno::XInterface /** returns a sequence of all types (usually interface types) provided by the object. - Important: If the object aggregates other objects the sequence also has + @attention + If the object aggregates other objects the sequence also has to contain all types supported by the aggregated objects. */ sequence getTypes(); @@ -43,14 +44,15 @@ published interface XTypeProvider: com::sun::star::uno::XInterface /** returns a sequence of bytes with length > 0 that is used as an Id to distinguish - unambiguously between two sets of types, e.g. to realise hashing + unambiguously between two sets of types, for example to realise hashing functionality when the object is introspected. Two objects that return the same UUID also have to return the same set of types in getTypes(). If a unique implementation Id cannot be provided this method has to return an empty sequence. - Important: If the object aggregates other objects the UUID has to be unique + @attention + If the object aggregates other objects the UUID has to be unique for the whole combination of objects. */ sequence getImplementationId(); diff --git a/udkapi/com/sun/star/uno/XCurrentContext.idl b/udkapi/com/sun/star/uno/XCurrentContext.idl index e5ba548a476f..f915efd2ad49 100644 --- a/udkapi/com/sun/star/uno/XCurrentContext.idl +++ b/udkapi/com/sun/star/uno/XCurrentContext.idl @@ -24,7 +24,7 @@ module com { module sun { module star { module uno { -/** Task (e.g. thread) local execution context for UNO. +/** Task (thread) local execution context for UNO. Arbitrary values can be retrieved from the context.

    You have to use UNO runtime functions to obtain the current context -- cgit v1.2.3