Improve documentation

Change-Id: I13683f971bf56f6c5e226d749e60ccb25af559a5

include/com/sun/star/uno/Any.h

@@ -249,6 +249,11 @@ template<> bool Any::has<sal_uInt16>() const SAL_DELETED_FUNCTION;
 
 /** Template function to generically construct an any from a C++ value.
 
+    This can be useful with an explicitly specified template parameter, when the
+    (UNO) type recorded in the Any instance shall be different from what would
+    be deduced from the (C++) type of the argument if no template parameter were
+    specified explicitly.
+
     @tparam C value type
     @param value a value
     @return an any

include/sal/types.h

@@ -502,13 +502,15 @@ template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
 #endif
 
 /**
-   This macro is used to tag interfaces that are deprecated for both
-   internal and external API users, but where we are still writing
-   out the internal usage. Ultimately these should be replaced by
-   SAL_DEPRECATED, and then removed.
-
-   Use as follows:
-        SAL_DEPRECATED_INTERNAL("Don't use, it's evil.") void doit(int nPara);
+   This macro is used in cppumaker-generated include files, to tag entities that
+   are marked as @deprecated in UNOIDL.
+
+   It causes deprecation warnings to be generated in external code, but for now
+   is silenced in internal code.  It would need some substantial clean-up of
+   internal code to fix all warnings/errors generated by it.  (Once that is
+   done, it can become a synonym for SAL_DEPRECATED under LIBO_INTERNAL_ONLY,
+   too.  Completely removing the macro then would be incompatible, in case thare
+   are include files still around generated with a cppumaker that emitted it.)
  */
 #ifdef LIBO_INTERNAL_ONLY
 #    define SAL_DEPRECATED_INTERNAL(message)