(maint) Confirm doxygen issues no warnings

Changes the doxygen test to use quiet output and scrape for any
warnings, as WARN_LOGFILE doesn't appear to work.

Also fix a few doxygen warnings. In particular, make Extensibility.md
part of the docs so we can use a relative reference.

Update Doxygen to 1.8.10; no strict requirement for this, only keeping
it up-to-date.

.travis.yml

@@ -32,12 +32,9 @@ before_install:
   - tar xjvf pcre-8.36_install.tar.bz2 --strip 1 -C $USERDIR
   - wget https://s3.amazonaws.com/kylo-pl-bucket/cppcheck-1.69_install.tar.bz2
   - tar xjvf cppcheck-1.69_install.tar.bz2 --strip 1 -C $USERDIR
-  # grab a pre-built doxygen 1.8.7 from s3
-  - wget https://s3.amazonaws.com/kylo-pl-bucket/doxygen_install.tar.bz2
-  - tar xjvf doxygen_install.tar.bz2 --strip 1 -C $USERDIR
-  # Install dependencies of cfacter
-  - wget https://s3.amazonaws.com/kylo-pl-bucket/yaml-cpp-0.5.1_install.tar.bz2
-  - tar xjvf yaml-cpp-0.5.1_install.tar.bz2 --strip 1 -C $USERDIR
+  # grab a pre-built doxygen 1.8.10
+  - wget https://s3.amazonaws.com/kylo-pl-bucket/doxygen-1.8.10.linux.bin.tar.gz
+  - tar xzvf doxygen-1.8.10.linux.bin.tar.gz --strip 1 -C $USERDIR
   # Install dependencies of facter
   - wget https://s3.amazonaws.com/kylo-pl-bucket/yaml-cpp-0.5.1_install.tar.bz2
   - tar xjvf yaml-cpp-0.5.1_install.tar.bz2 --strip 1 -C $USERDIR

README.md

@@ -7,7 +7,7 @@ An implementation of facter functionality in C++11, providing:
 * an executable for standalone command line usage
 * a ruby file to enable `require 'facter'`.
 
-Please see our [extensibility document](https://github.com/puppetlabs/facter/blob/master/Extensibility.md) to learn more
+Please see our [extensibility document](Extensibility.md) to learn more
 about extending native facter using custom and external facts.
 
 Build Requirements

lib/Doxyfile

@@ -694,7 +694,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES
@@ -755,6 +755,7 @@ WARN_LOGFILE           = html/warnings.txt
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = ../README.md \
+                         ../Extensibility.md \
                          inc \
                          docs
 

lib/inc/facter/facts/collection.hpp

@@ -224,6 +224,10 @@ namespace facter { namespace facts {
         void resolve_facts();
 
      protected:
+        /**
+         *  Gets external fact directories for the current platform.
+         *  @return A list of file paths that will be searched for external facts.
+         */
         virtual std::vector<std::string> get_external_fact_directories() const;
 
      private:

lib/inc/facter/logging/logging.hpp

@@ -159,7 +159,7 @@ namespace facter { namespace logging {
     /**
      * Starts colorizing for the given logging level.
      * This is a no-op on platforms that don't natively support terminal colors.
-     * @param dst The stream to colorize.
+     * @param os The stream to colorize.
      * @param lvl The logging level to colorize for. Defaults to none, which resets colorization.
      */
     LIBFACTER_EXPORT void colorize(std::ostream &os, level lvl = level::none);

scripts/travis_target.sh

@@ -37,9 +37,8 @@ function travis_make()
     if [ $1 == "cpplint" ]; then
         # Verify documentation
         pushd ../lib
-        doxygen
-        if [[ -s html/warnings.txt ]]; then
-            cat html/warnings.txt
+        doxygen 2>&1 | ( ! grep . )
+        if [ $? -ne 0 ]; then
             echo "documentation failed."
             exit 1
         fi