*api: tweak docs

Change-Id: Icc470b284cc511facbe7479d3d04f033ec4e19e5

11 files changed, 38 insertions, 33 deletions

diff --git a/offapi/com/sun/star/task/InteractionHandler.idl b/offapi/com/sun/star/task/InteractionHandler.idl
index 5c0bca04b601..48f8dd7360dc 100644
--- a/offapi/com/sun/star/task/InteractionHandler.idl
+++ b/offapi/com/sun/star/task/InteractionHandler.idl
@@ -39,7 +39,6 @@ module com { module sun { module star { module task {
     <UL>
         <LI>com::sun::star::ucb::AuthenticationRequest</LI>
         <LI>com::sun::star::ucb::CertificateValidationRequest</LI>
-        <LI>com::sun::star::ucb::HandleCookiesRequest</LI>
         <LI>com::sun::star::ucb::InteractiveAugmentedIOException*</LI>
         <LI>com::sun::star::ucb::InteractiveFileIOException*</LI>
         <LI>com::sun::star::ucb::InteractiveIOException*</LI>
diff --git a/offapi/com/sun/star/task/PasswordContainerInteractionHandler.idl b/offapi/com/sun/star/task/PasswordContainerInteractionHandler.idl
index 76e4f5af5a4c..e973a54641f8 100644
--- a/offapi/com/sun/star/task/PasswordContainerInteractionHandler.idl
+++ b/offapi/com/sun/star/task/PasswordContainerInteractionHandler.idl
@@ -28,7 +28,7 @@ module com { module sun { module star { module task {
 
 /** An interaction request handler that uses the
     com::sun::star::task::PasswordContainer service to
-    handle com::sun::star::ucb::AuthenticationRequests.
+    handle com::sun::star::ucb::AuthenticationRequest.
 
     If the password container contains credentials matching the authentication
     request, the service implementation selects the
diff --git a/offapi/com/sun/star/util/RevisionTag.idl b/offapi/com/sun/star/util/RevisionTag.idl
index 998334effb2e..9a1ac368d7d6 100644
--- a/offapi/com/sun/star/util/RevisionTag.idl
+++ b/offapi/com/sun/star/util/RevisionTag.idl
@@ -25,7 +25,7 @@
 module com {  module sun {  module star {  module util {
 
 
-/** represents the information that describes a revision of something, f.e. a document
+/** represents the information that describes a revision of something.
  */
 struct RevisionTag
 {
diff --git a/offapi/com/sun/star/util/SearchResult.idl b/offapi/com/sun/star/util/SearchResult.idl
index 6a81207cea3b..8f14de88bfc2 100644
--- a/offapi/com/sun/star/util/SearchResult.idl
+++ b/offapi/com/sun/star/util/SearchResult.idl
@@ -26,13 +26,19 @@ module com { module sun { module star { module util {
 
 
 published  struct SearchResult  {
-    /** Number of subexpressions,
-    if it is 0, then no match found; this value is 1 for ABSOLUTE and APPROXIMATE match.
+
+    /** Number of subexpressions.
+
+    If it is 0, then no match found; this value is 1 for ABSOLUTE
+    and APPROXIMATE match.
     The start and endOffset are always dependent on the search direction.
-    For example:
-    if you search "X" in the text "-X-" the offset are:
-        for forward:     start = 1, end = 2
+
+    For example, if you search "X" in the text "-X-" the offsets are:
+
+        for forward:    start = 1, end = 2
+
         for backward:   start = 2, end = 1
+
     Forward, the startOffset is inclusive, the endOffset exclusive.
     Backward, the startOffset is exclusive, the endOffset inclusive.
 
@@ -42,8 +48,8 @@ published  struct SearchResult  {
     startoffset[i] and endoffset[i] points to the matching substring of i th matching substring.
     */
     long subRegExpressions;
-    sequence<long> startOffset;        // inclusive
-    sequence<long> endOffset;          // exclusive
+    sequence<long> startOffset;
+    sequence<long> endOffset;
 };
 
 }; }; }; };
diff --git a/offapi/com/sun/star/util/SortDescriptor.idl b/offapi/com/sun/star/util/SortDescriptor.idl
index 4854064da1ba..330935953dc1 100644
--- a/offapi/com/sun/star/util/SortDescriptor.idl
+++ b/offapi/com/sun/star/util/SortDescriptor.idl
@@ -44,10 +44,10 @@ published service SortDescriptor
 
     /** specifies the sorting order.
 
-            The sorting order may be defined for separate keys in specific
-            implementations. For those this property may not need to be set.
+        The sorting order may be defined for separate keys in specific
+        implementations. For those this property may not need to be set.
 
-            @see com::sun::star::text::TextSortDescriptor
+        @see com::sun::star::text::TextSortDescriptor
      */
         [optional, property] boolean SortAscending;
 
@@ -75,12 +75,12 @@ published service SortDescriptor
 
     /** specifies the algorithm for the compare operator (collator).
 
-            The collator algorithm may be defined for separate keys in specific
-            implementations. For those this property may not need to be set.
+        The collator algorithm may be defined for separate keys in specific
+        implementations. For those this property may not need to be set.
 
-            @see com::sun::star::text::TextSortDescriptor
+        @see com::sun::star::text::TextSortDescriptor
 
-            @see com::sun::star::i18n::XCollator
+        @see com::sun::star::i18n::XCollator
      */
         [optional, property] string CollatorAlgorithm;
 };
diff --git a/offapi/com/sun/star/util/XBroadcaster.idl b/offapi/com/sun/star/util/XBroadcaster.idl
index 513c2db8e699..f0a4fd250499 100644
--- a/offapi/com/sun/star/util/XBroadcaster.idl
+++ b/offapi/com/sun/star/util/XBroadcaster.idl
@@ -34,7 +34,7 @@ interface XBroadcaster: com::sun::star::uno::XInterface
     /** suspends broadcasts to the registered listeners.
 
         <p>
-        The calls to XBroadcaster::lockBroadcast() and
+        The calls to XBroadcaster::lockBroadcasts() and
         XBroadcaster::unlockBroadcasts() may be
         nested and even overlapping, but they must be in pairs. While
         there is at least one lock remaining, no broadcasts are
@@ -47,7 +47,7 @@ interface XBroadcaster: com::sun::star::uno::XInterface
         XBroadcaster::lockBroadcasts().
 
         <p>
-        The calls to XBroadcaster::lockBroadcast() and
+        The calls to XBroadcaster::lockBroadcasts() and
         XBroadcaster::unlockBroadcasts() may be
         nested and even overlapping, but they must be in pairs. While
         there is at least one lock remaining, no broadcasts are
@@ -55,7 +55,7 @@ interface XBroadcaster: com::sun::star::uno::XInterface
         </p>
 
         <p> Pending broadcasts will be sent immediately after the last
-        call to XBroadcaster::lockBroadcast() is matched
+        call to XBroadcaster::lockBroadcasts() is matched
         by a call to XBroadcaster::unlockBroadcasts().
         An implementation can decide to broadcast all pending notification in
         order or batch them in single broadcasts.
diff --git a/offapi/com/sun/star/util/XDataEditor.idl b/offapi/com/sun/star/util/XDataEditor.idl
index c6e84ea3fc3d..09fa8397b91c 100644
--- a/offapi/com/sun/star/util/XDataEditor.idl
+++ b/offapi/com/sun/star/util/XDataEditor.idl
@@ -43,11 +43,11 @@ published interface XDataEditor: com::sun::star::uno::XInterface
      */
     com::sun::star::uno::XInterface getModel();
 
-    /** registers a listener to receive DataEditorEvents.
+    /** registers a listener to receive `DataEditorEvent`s.
      */
     void addDataEditorListener( [in] XDataEditorListener listener );
 
-    /** unregisters a listener which received DataEditorEvents.
+    /** unregisters a listener.
      */
     void removeDataEditorListener( [in] XDataEditorListener listener );
 };
diff --git a/offapi/com/sun/star/util/XOfficeInstallationDirectories.idl b/offapi/com/sun/star/util/XOfficeInstallationDirectories.idl
index 4a471e6fbb60..e9dc1e61fed7 100644
--- a/offapi/com/sun/star/util/XOfficeInstallationDirectories.idl
+++ b/offapi/com/sun/star/util/XOfficeInstallationDirectories.idl
@@ -39,7 +39,7 @@ module com { module sun { module star { module util {
 published interface XOfficeInstallationDirectories : com::sun::star::uno::XInterface
 {
     /** returns the absolute URL containing the directory of the current office
-        installation (e.g. "file:///opt/OpenOffice.org".)
+        installation (for example "file:///opt/LibreOffice")
 
         @returns
         the absolute URL containing the directory of the current office
@@ -48,8 +48,8 @@ published interface XOfficeInstallationDirectories : com::sun::star::uno::XInter
     string getOfficeInstallationDirectoryURL();
 
     /** returns the absolute URL containing the directory where the current
-        office installation expects its user data (e.g.
-        "file:///home/kso/.openoffice.org".)
+        office installation expects its user data (for example
+        "file:///home/kso/.config/libreoffice/4")
 
         @returns
         the absolute URL containing the directory of the current office
diff --git a/offapi/com/sun/star/util/XSearchable.idl b/offapi/com/sun/star/util/XSearchable.idl
index 9420e2abb853..9a18ad58cc31 100644
--- a/offapi/com/sun/star/util/XSearchable.idl
+++ b/offapi/com/sun/star/util/XSearchable.idl
@@ -40,8 +40,8 @@ module com {  module sun {  module star {  module util {
     @code{.bas}
     xSearchDescr = xDocument.createSearchDescriptor()
     xSearchDescr.SearchString = "search for"
-    xSearchDescr.SearchCaseSensitive = `TRUE`
-    xSearchDescr.SearchWords = `TRUE`
+    xSearchDescr.SearchCaseSensitive = true
+    xSearchDescr.SearchWords = true
     xFound = xDocument.findFirst( xSearchDescr )
     do while not IsNull(xFound)
     xFound.CharWeight = com.sun.star.awt.FontWeight.BOLD
diff --git a/offapi/com/sun/star/util/XURLTransformer.idl b/offapi/com/sun/star/util/XURLTransformer.idl
index 734fc7754793..9a6efdb83ea1 100644
--- a/offapi/com/sun/star/util/XURLTransformer.idl
+++ b/offapi/com/sun/star/util/XURLTransformer.idl
@@ -70,8 +70,8 @@ published interface XURLTransformer: com::sun::star::uno::XInterface
 
         @param sSmartProtocol
                 optional information which protocol specification should be used to parse
-                memberURL::Complete. If empty the implementation can use a
-                protocol which fit best.
+                URL::Complete. If empty the implementation can use a
+                protocol which fits best.
 
         @returns
                 `TRUE` if parsing was successful (means if URL::Complete could
@@ -87,8 +87,8 @@ published interface XURLTransformer: com::sun::star::uno::XInterface
         @param aURL
                 the URL which contains alls necessary information in a structured form. The
                 member URL::Complete contains the URL in string notation after
-                the operation finished successfully. Otherwise the content of URL::complete()
-                is not defined.
+                the operation finished successfully. Otherwise the content of
+                URL::Complete is not defined.
 
         @returns
             `TRUE` if assembling was successfully or `FALSE` otherwise.
diff --git a/udkapi/com/sun/star/task/XInteractionContinuation.idl b/udkapi/com/sun/star/task/XInteractionContinuation.idl
index 5724fd257b6a..d4fcf0aa19a4 100644
--- a/udkapi/com/sun/star/task/XInteractionContinuation.idl
+++ b/udkapi/com/sun/star/task/XInteractionContinuation.idl
@@ -34,8 +34,8 @@ published interface XInteractionContinuation: com::sun::star::uno::XInterface
 {
     /** Select this way of continuing from an
         com::sun::star::task::XInteractionRequest (given a
-        choice of various
-        com::sun::star::task::XInteractionContinuations).
+        choice of various instances of
+        com::sun::star::task::XInteractionContinuation).
      */
     void select();