*api: tweak docs

Change-Id: I20878a3977fe7b3ab7e733a7bc0d704fb5835009

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;
 

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 <code>"/-"</code>
     indicates (recursively) all files and subdirectories contained in that
     directory.  A file url string consisting of the special token
-    <code>"&lt;&lt;ALL FILES&gt;&gt;"</code> matches any file.
+    <code>"<<ALL FILES>>"</code> matches any file.
     <br>
     Note: A file url string consisting of a single <code>"*"</code> indicates all the files
     in the current directory, while a string consisting of a single <code>"-"</code> 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 <code>"&lt;&lt;ALL FILES&gt;&gt;"</code> permission with write action is
+    The <code>"<<ALL FILES>>"</code> permission with write action is
     especially dangerous.  This grants permission to write to the entire file system.
 
     @since OOo 1.1.2

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.  </p>
-       @param aData
+
+        @param aData
              after the call, the byte sequence contains the requested number
              of bytes (or less as a sign of EOF).
-
-             <p>
+             <br>
              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
               <li> the call is not bridged (e.g., betweeen different compilers
                    or different processes ).
              </ol>
-
+             <br>
              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<byte> 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
 
         <p>It is up to the implementation whether this method is
         blocking the thread or not.  </p>
-      @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,

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.
-
         <p>This name is used to create such an object by a factory
         during deserialization. </p>
 
-        @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();
 

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.</p>
+        when it gets called.</p>
 
         <p>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
         <p>It is suggested to allow multiple registration of the same listener,
         thus for each time a listener is added, it has to be removed.</p>
 
-        <p>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()
+        <p>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.</p>
+        addEventListener() call.</p>
 
         @see XComponent::removeEventListener
      */
@@ -101,11 +98,9 @@ published interface XComponent: com::sun::star::uno::XInterface
         <p>It is suggested to allow multiple registration of the same listener,
         thus for each time a listener is added, it has to be removed.
 
-        <p>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,
+        <p>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.</p>
 
         @see XComponent::addEventListener

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.
-
-    <p>
-    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.
-    </p>
+/** 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
 {

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

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<type> 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<byte> getImplementationId();

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.
     <p>
     You have to use UNO runtime functions to obtain the current context