...as there are typically no direct calls to it anyway.  What is apparently
needed is to decorate the cppumaker-generated headers instead:

* cppumaker obtains deprecation-information from the documentation strings in
  .rdb files.  As these are normally generated by idlc without documentation
  included (no -C), idlc got changed to nevertheless contain documentation
  consisting of just "@deprecated" in this case, to allow to easily tunnel this
  information to cppumaker always.

* The mechanism of parsing for "@deprecated" in documentation strings is
  somewhat crude, of course.

* For now, cppumaker only decorates C++ functions that correspond to UNOIDL
  interface attributes and methods.  More should be possible (but, e.g., being
  able to decorate a complete C++ class corresponding to a deprecated UNOIDL
  interface type depends on whether all platforms would accept
  SAL_DEPRECATED_INTERNAL at the same position in a C++ class declaration.

* This could also be extended to other languages than C++/cppumaker.

* Always using SAL_DEPRECATED_INERNAL instead of SAL_DEPRECATED for decoration
  is to keep things simple and our codebase working.  Improvements are possible
  here, too, of course.

Change-Id: Ia2917892f780d477652e4cd9f286588a6898c3f5