Add documentation To .R file.

src/mlpack/bindings/R/CMakeLists.txt

@@ -129,8 +129,12 @@ if (BUILD_R_BINDINGS)
 
   set(BINDINGS_SOURCES
     "${CMAKE_CURRENT_SOURCE_DIR}/get_type.hpp"
-    "${CMAKE_CURRENT_SOURCE_DIR}/ignore_check.hpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/print_doc.hpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/print_doc_functions.hpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/print_doc_functions_impl.hpp"
     "${CMAKE_CURRENT_SOURCE_DIR}/print_input_param.hpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/get_param.hpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/get_printable_param.hpp"
     "${CMAKE_CURRENT_SOURCE_DIR}/print_input_processing.hpp"
     "${CMAKE_CURRENT_SOURCE_DIR}/print_output_processing.hpp"
     "${CMAKE_CURRENT_SOURCE_DIR}/print_serialize_util.hpp"

src/mlpack/bindings/R/R_option.hpp

@@ -12,9 +12,12 @@
 #ifndef MLPACK_BINDINGS_R_R_OPTION_HPP
 #define MLPACK_BINDINGS_R_R_OPTION_HPP
 #include <mlpack/core/util/param_data.hpp>
+#include "get_param.hpp"
+#include "get_printable_param.hpp"
 #include "print_input_param.hpp"
 #include "print_input_processing.hpp"
 #include "print_output_processing.hpp"
+#include "print_doc.hpp"
 #include "print_serialize_util.hpp"
 
 namespace mlpack {
@@ -82,7 +85,16 @@ class ROption
     if (identifier != "verbose")
       CLI::RestoreSettings(CLI::ProgramName(), false);
 
+    // Set the function pointers that we'll need.  All of these function
+    // pointers will be used by both the program that generates the R, and
+    // also the binding itself.  (The binding itself will only use GetParam,
+    // GetPrintableParam, and GetRawParam.)
+    CLI::GetSingleton().functionMap[data.tname]["GetParam"] = &GetParam<T>;
+    CLI::GetSingleton().functionMap[data.tname]["GetPrintableParam"] =
+        &GetPrintableParam<T>;
+
     // These are used by the R generator.
+    CLI::GetSingleton().functionMap[data.tname]["PrintDoc"] = &PrintDoc<T>;
     CLI::GetSingleton().functionMap[data.tname]["PrintInputParam"] =
         &PrintInputParam<T>;
     CLI::GetSingleton().functionMap[data.tname]["PrintOutputProcessing"] =

src/mlpack/bindings/R/get_param.hpp

@@ -0,0 +1,37 @@
+/**
+ * @file bindings/R/get_param.hpp
+ * @author Yashwant Singh Parihar
+ *
+ * Get a parameter for a R binding.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+#ifndef MLPACK_BINDINGS_R_GET_PARAM_HPP
+#define MLPACK_BINDINGS_R_GET_PARAM_HPP
+
+#include <mlpack/prereqs.hpp>
+
+namespace mlpack {
+namespace bindings {
+namespace r {
+
+/**
+ * All R binding types are exactly what is held in the ParamData, so no
+ * special handling is necessary.
+ */
+template<typename T>
+void GetParam(const util::ParamData& d,
+              const void* /* input */,
+              void* output)
+{
+  *((T**) output) = const_cast<T*>(boost::any_cast<T>(&d.value));
+}
+
+} // namespace r
+} // namespace bindings
+} // namespace mlpack
+
+#endif

src/mlpack/bindings/R/get_printable_param.hpp

@@ -0,0 +1,126 @@
+/**
+ * @file bindings/R/get_printable_param.hpp
+ * @author Yashwant Singh Parihar
+ *
+ * Get a printable version of parameters.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+#ifndef MLPACK_BINDINGS_R_GET_PRINTABLE_PARAM_HPP
+#define MLPACK_BINDINGS_R_GET_PRINTABLE_PARAM_HPP
+
+#include <mlpack/prereqs.hpp>
+#include <mlpack/core/util/is_std_vector.hpp>
+
+namespace mlpack {
+namespace bindings {
+namespace r {
+
+/**
+ * Print an option of a simple type.
+ */
+template<typename T>
+std::string GetPrintableParam(
+    const util::ParamData& data,
+    const typename boost::disable_if<arma::is_arma_type<T>>::type* = 0,
+    const typename boost::disable_if<util::IsStdVector<T>>::type* = 0,
+    const typename boost::disable_if<data::HasSerialize<T>>::type* = 0,
+    const typename boost::disable_if<std::is_same<T,
+        std::tuple<data::DatasetInfo, arma::mat>>>::type* = 0)
+{
+  std::ostringstream oss;
+  oss << boost::any_cast<T>(data.value);
+  return oss.str();
+}
+
+/**
+ * Print a vector option, with spaces between it.
+ */
+template<typename T>
+std::string GetPrintableParam(
+    const util::ParamData& data,
+    const typename boost::enable_if<util::IsStdVector<T>>::type* = 0)
+{
+  const T& t = boost::any_cast<T>(data.value);
+
+  std::ostringstream oss;
+  for (size_t i = 0; i < t.size(); ++i)
+    oss << t[i] << " ";
+  return oss.str();
+}
+
+/**
+ * Print a matrix option (this prints its size).
+ */
+template<typename T>
+std::string GetPrintableParam(
+    const util::ParamData& data,
+    const typename boost::enable_if<arma::is_arma_type<T>>::type* = 0)
+{
+  // Get the matrix.
+  const T& matrix = boost::any_cast<T>(data.value);
+
+  std::ostringstream oss;
+  oss << matrix.n_rows << "x" << matrix.n_cols << " matrix";
+  return oss.str();
+}
+
+/**
+ * Print a serializable class option (this prints the class name).
+ */
+template<typename T>
+std::string GetPrintableParam(
+    const util::ParamData& data,
+    const typename boost::disable_if<arma::is_arma_type<T>>::type* = 0,
+    const typename boost::enable_if<data::HasSerialize<T>>::type* = 0)
+{
+  std::ostringstream oss;
+  oss << data.cppType << " model at " << boost::any_cast<T*>(data.value);
+  return oss.str();
+}
+
+/**
+ * Print a combination DatasetInfo/matrix parameter.
+ */
+template<typename T>
+std::string GetPrintableParam(
+    const util::ParamData& data,
+    const typename boost::enable_if<std::is_same<T,
+        std::tuple<data::DatasetInfo, arma::mat>>>::type* = 0)
+{
+  // Get the matrix.
+  const T& tuple = boost::any_cast<T>(data.value);
+  const arma::mat& matrix = std::get<1>(tuple);
+
+  std::ostringstream oss;
+  oss << matrix.n_rows << "x" << matrix.n_cols << " matrix with dimension type "
+      << "information";
+  return oss.str();
+}
+
+/**
+ * Print an option into a std::string.  This should print a short, one-line
+ * representation of the object.  The string will be stored in the output
+ * pointer.
+ *
+ * @param data Parameter data struct.
+ * @param * (input) Unused parameter.
+ * @param output Output storage for the string.
+ */
+template<typename T>
+void GetPrintableParam(const util::ParamData& data,
+                       const void* /* input */,
+                       void* output)
+{
+  *((std::string*) output) =
+      GetPrintableParam<typename std::remove_pointer<T>::type>(data);
+}
+
+} // namespace r
+} // namespace bindings
+} // namespace mlpack
+
+#endif

src/mlpack/bindings/R/print_R.cpp

@@ -62,6 +62,49 @@ void PrintR(const util::ProgramDoc& programInfo,
       inputOptions.push_back(it->first);
   }
 
+  // Print the documentation.
+  cout << "#' @title ";
+  cout << util::HyphenateString(programInfo.programName, "#'   ") << endl;
+  cout << "#'" << endl;
+
+  // Next print the description.
+  cout << "#' @description" << endl;
+  cout << "#' ";
+  cout << util::HyphenateString(programInfo.documentation(), "#' ") << endl;
+
+  // Next, print information on the input options.
+  cout << "#'" << endl;
+
+  for (size_t i = 0; i < inputOptions.size(); ++i)
+  {
+    const string& opt = inputOptions[i];
+    const util::ParamData& d = parameters.at(opt);
+
+    cout << "#' @param ";
+    bool out = false;
+    CLI::GetSingleton().functionMap[d.tname]["PrintDoc"](d, NULL, (void*) &out);
+
+    cout << endl;
+  }
+
+  cout << "#'" << endl;
+  cout << "#' @return A list with several components:" << endl;
+
+  for (size_t i = 0; i < outputOptions.size(); ++i)
+  {
+    const string& opt = outputOptions[i];
+    const util::ParamData& d = parameters.at(opt);
+
+    cout << "#' \\item{";
+
+    bool out = true;
+    CLI::GetSingleton().functionMap[d.tname]["PrintDoc"](d, NULL, (void*) &out);
+
+    cout << endl;
+  }
+
+  cout << "#'" << endl;
+
   cout << "#' @export" << endl;
   cout << functionName << " <- function(";
   size_t indent = functionName.size() + 13 /* <- function(*/;

src/mlpack/bindings/R/print_doc.hpp

@@ -0,0 +1,87 @@
+/**
+ * @file bindings/R/print_doc.hpp
+ * @author Yashwant Singh Parihar.
+ *
+ * Print documentation for a R binding parameter.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+#ifndef MLPACK_BINDINGS_R_PRINT_DOC_HPP
+#define MLPACK_BINDINGS_R_PRINT_DOC_HPP
+
+#include <mlpack/prereqs.hpp>
+#include <mlpack/core/util/hyphenate_string.hpp>
+
+namespace mlpack {
+namespace bindings {
+namespace r {
+
+/**
+ * Print the docstring documentation for a given parameter.  You are responsible
+ * for setting up the line---this does not handle indentation or anything.  This
+ * is meant to produce a line of documentation describing a single parameter.
+ *
+ * The indent parameter (void* input, which should be a pointer to a size_t)
+ * should be passed to know how much to indent for a new line.
+ *
+ * @param d Parameter data struct.
+ * @param input Pointer to size_t containing indent.
+ * @param output Unused parameter.
+ */
+template<typename T>
+void PrintDoc(const util::ParamData& d,
+              const void* /* input */,
+              void* output)
+{
+
+  bool out = *((bool*) output);
+  std::ostringstream oss;
+  oss << d.name;
+  if (out)
+    oss << "}{";
+  else
+    oss << " ";
+  oss << d.desc;
+  // Print a default, if possible.
+  if (!d.required)
+  {
+    if (d.cppType == "std::string" ||
+        d.cppType == "double" ||
+        d.cppType == "int" ||
+        d.cppType == "bool")
+    {
+      oss << "  Default value \"";
+      if (d.cppType == "std::string")
+      {
+        oss << boost::any_cast<std::string>(d.value);
+      }
+      else if (d.cppType == "double")
+      {
+        oss << boost::any_cast<double>(d.value);
+      }
+      else if (d.cppType == "int")
+      {
+        oss << boost::any_cast<int>(d.value);
+      }
+      else if (d.cppType == "bool")
+      {
+        oss << (boost::any_cast<bool>(d.value) ? "TRUE" : "FALSE");
+      }
+      oss << "\".";
+    }
+  }
+
+  if (out)
+    oss << "}";
+
+  std::cout << util::HyphenateString(oss.str(), "#'   ");
+}
+
+} // namespace r
+} // namespace bindings
+} // namespace mlpack
+
+#endif