[1063] Document the internal function

Finder.getRRset is documented even when it is private and internal, as
it has complicated interface (which might use some simplification).

src/lib/datasrc/database.h

@@ -290,7 +290,37 @@ public:
     private:
         boost::shared_ptr<DatabaseAccessor> database_;
         const int zone_id_;
-        /// \brief Searches database for an RRset
+        /**
+         * \brief Searches database for an RRset
+         *
+         * This method scans RRs of single domain specified by name and finds
+         * RRset with given type or any of redirection RRsets that are
+         * requested.
+         *
+         * This function is used internally by find(), because this part is
+         * called multiple times with slightly different parameters.
+         *
+         * \param name Which domain name should be scanned.
+         * \param type The RRType which is requested. This can be NULL, in
+         *     which case the method will look for the redirections only.
+         * \param want_cname If this is true, CNAME redirection may be returned
+         *     instead of the RRset with given type. If there's CNAME and
+         *     something else or the CNAME has multiple RRs, it throws
+         *     DataSourceError.
+         * \param want_dname If this is true, DNAME redirection may be returned
+         *     instead. This is with type = NULL only and is not checked in
+         *     other circumstances. If the DNAME has multiple RRs, it throws
+         *     DataSourceError.
+         * \param want_ns This allows redirection by NS to be returned.
+         * \todo When want_ns is true and there's another RRtype, we should
+         *     throw, but we don't yet.
+         * \return First part of the result tells if the domain contains any
+         *     RRs. This can be used to decide between NXDOMAIN and NXRRSET.
+         *     The second part is the RRset found (if any) with any relevant
+         *     signatures attached to it.
+         * \todo This interface doesn't look very elegant. Any better idea
+         *     would be nice.
+         */
         std::pair<bool, isc::dns::RRsetPtr> getRRset(const isc::dns::Name&
                                                      name,
                                                      const isc::dns::RRType*