Style cleanup of javadoc-style comments

This changes javadoc-style documenting comments from:

    /** Text starts here
     * and continues here
     */

to:

    /**
     * Test starts here
     * and continues here
     */

which looks a little better, and also matches the javadoc-recommended
way of writing documenting comments.

include/pybind11/attr.h

@@ -415,7 +415,7 @@ struct process_attribute<arithmetic> : process_attribute_default<arithmetic> {};
 template <typename... Ts>
 template <typename... Ts>
 struct process_attribute<call_guard<Ts...>> : process_attribute_default<call_guard<Ts...>> { };
 struct process_attribute<call_guard<Ts...>> : process_attribute_default<call_guard<Ts...>> { };
 
 
-/***
+/**
  * Process a keep_alive call policy -- invokes keep_alive_impl during the
  * Process a keep_alive call policy -- invokes keep_alive_impl during the
  * pre-call handler if both Nurse, Patient != 0 and use the post-call handler
  * pre-call handler if both Nurse, Patient != 0 and use the post-call handler
  * otherwise
  * otherwise

include/pybind11/cast.h

@@ -34,7 +34,7 @@ struct type_info {
     std::vector<bool (*)(PyObject *, void *&)> *direct_conversions;
     std::vector<bool (*)(PyObject *, void *&)> *direct_conversions;
     buffer_info *(*get_buffer)(PyObject *, void *) = nullptr;
     buffer_info *(*get_buffer)(PyObject *, void *) = nullptr;
     void *get_buffer_data = nullptr;
     void *get_buffer_data = nullptr;
-    /** A simple type never occurs as a (direct or indirect) parent
+    /* A simple type never occurs as a (direct or indirect) parent
      * of a class that makes use of multiple inheritance */
      * of a class that makes use of multiple inheritance */
     bool simple_type : 1;
     bool simple_type : 1;
     /* True if there is no multiple inheritance in this type's inheritance tree */
     /* True if there is no multiple inheritance in this type's inheritance tree */

include/pybind11/class_support.h

@@ -150,7 +150,8 @@ extern "C" inline int pybind11_meta_setattro(PyObject* obj, PyObject* name, PyOb
 }
 }
 
 
 #if PY_MAJOR_VERSION >= 3
 #if PY_MAJOR_VERSION >= 3
-/** Python 3's PyInstanceMethod_Type hides itself via its tp_descr_get, which prevents aliasing
+/**
+ * Python 3's PyInstanceMethod_Type hides itself via its tp_descr_get, which prevents aliasing
  * methods via cls.attr("m2") = cls.attr("m1"): instead the tp_descr_get returns a plain function,
  * methods via cls.attr("m2") = cls.attr("m1"): instead the tp_descr_get returns a plain function,
  * when called on a class, or a PyMethod, when called on an instance.  Override that behaviour here
  * when called on a class, or a PyMethod, when called on an instance.  Override that behaviour here
  * to do a special case bypass for PyInstanceMethod_Types.
  * to do a special case bypass for PyInstanceMethod_Types.

include/pybind11/numpy.h

@@ -304,7 +304,8 @@ ssize_t byte_offset_unsafe(const Strides &strides, ssize_t i, Ix... index) {
     return i * strides[Dim] + byte_offset_unsafe<Dim + 1>(strides, index...);
     return i * strides[Dim] + byte_offset_unsafe<Dim + 1>(strides, index...);
 }
 }
 
 
-/** Proxy class providing unsafe, unchecked const access to array data.  This is constructed through
+/**
+ * Proxy class providing unsafe, unchecked const access to array data.  This is constructed through
  * the `unchecked<T, N>()` method of `array` or the `unchecked<N>()` method of `array_t<T>`.  `Dims`
  * the `unchecked<T, N>()` method of `array` or the `unchecked<N>()` method of `array_t<T>`.  `Dims`
  * will be -1 for dimensions determined at runtime.
  * will be -1 for dimensions determined at runtime.
  */
  */
@@ -335,7 +336,8 @@ protected:
     : data_{reinterpret_cast<const unsigned char *>(data)}, shape_{shape}, strides_{strides}, dims_{dims} {}
     : data_{reinterpret_cast<const unsigned char *>(data)}, shape_{shape}, strides_{strides}, dims_{dims} {}
 
 
 public:
 public:
-    /** Unchecked const reference access to data at the given indices.  For a compile-time known
+    /**
+     * Unchecked const reference access to data at the given indices.  For a compile-time known
      * number of dimensions, this requires the correct number of arguments; for run-time
      * number of dimensions, this requires the correct number of arguments; for run-time
      * dimensionality, this is not checked (and so is up to the caller to use safely).
      * dimensionality, this is not checked (and so is up to the caller to use safely).
      */
      */
@@ -344,7 +346,8 @@ public:
                 "Invalid number of indices for unchecked array reference");
                 "Invalid number of indices for unchecked array reference");
         return *reinterpret_cast<const T *>(data_ + byte_offset_unsafe(strides_, ssize_t(index)...));
         return *reinterpret_cast<const T *>(data_ + byte_offset_unsafe(strides_, ssize_t(index)...));
     }
     }
-    /** Unchecked const reference access to data; this operator only participates if the reference
+    /**
+     * Unchecked const reference access to data; this operator only participates if the reference
      * is to a 1-dimensional array.  When present, this is exactly equivalent to `obj(index)`.
      * is to a 1-dimensional array.  When present, this is exactly equivalent to `obj(index)`.
      */
      */
     template <ssize_t D = Dims, typename = enable_if_t<D == 1 || Dynamic>>
     template <ssize_t D = Dims, typename = enable_if_t<D == 1 || Dynamic>>
@@ -392,7 +395,8 @@ public:
                 "Invalid number of indices for unchecked array reference");
                 "Invalid number of indices for unchecked array reference");
         return const_cast<T &>(ConstBase::operator()(index...));
         return const_cast<T &>(ConstBase::operator()(index...));
     }
     }
-    /** Mutable, unchecked access data at the given index; this operator only participates if the
+    /**
+     * Mutable, unchecked access data at the given index; this operator only participates if the
      * reference is to a 1-dimensional array (or has runtime dimensions).  When present, this is
      * reference is to a 1-dimensional array (or has runtime dimensions).  When present, this is
      * exactly equivalent to `obj(index)`.
      * exactly equivalent to `obj(index)`.
      */
      */
@@ -679,7 +683,8 @@ public:
         return offset_at(index...) / itemsize();
         return offset_at(index...) / itemsize();
     }
     }
 
 
-    /** Returns a proxy object that provides access to the array's data without bounds or
+    /**
+     * Returns a proxy object that provides access to the array's data without bounds or
      * dimensionality checking.  Will throw if the array is missing the `writeable` flag.  Use with
      * dimensionality checking.  Will throw if the array is missing the `writeable` flag.  Use with
      * care: the array must not be destroyed or reshaped for the duration of the returned object,
      * care: the array must not be destroyed or reshaped for the duration of the returned object,
      * and the caller must take care not to access invalid dimensions or dimension indices.
      * and the caller must take care not to access invalid dimensions or dimension indices.
@@ -691,7 +696,8 @@ public:
         return detail::unchecked_mutable_reference<T, Dims>(mutable_data(), shape(), strides(), ndim());
         return detail::unchecked_mutable_reference<T, Dims>(mutable_data(), shape(), strides(), ndim());
     }
     }
 
 
-    /** Returns a proxy object that provides const access to the array's data without bounds or
+    /**
+     * Returns a proxy object that provides const access to the array's data without bounds or
      * dimensionality checking.  Unlike `mutable_unchecked()`, this does not require that the
      * dimensionality checking.  Unlike `mutable_unchecked()`, this does not require that the
      * underlying array have the `writable` flag.  Use with care: the array must not be destroyed or
      * underlying array have the `writable` flag.  Use with care: the array must not be destroyed or
      * reshaped for the duration of the returned object, and the caller must take care not to access
      * reshaped for the duration of the returned object, and the caller must take care not to access
@@ -851,7 +857,8 @@ public:
         return *(static_cast<T*>(array::mutable_data()) + byte_offset(ssize_t(index)...) / itemsize());
         return *(static_cast<T*>(array::mutable_data()) + byte_offset(ssize_t(index)...) / itemsize());
     }
     }
 
 
-    /** Returns a proxy object that provides access to the array's data without bounds or
+    /**
+     * Returns a proxy object that provides access to the array's data without bounds or
      * dimensionality checking.  Will throw if the array is missing the `writeable` flag.  Use with
      * dimensionality checking.  Will throw if the array is missing the `writeable` flag.  Use with
      * care: the array must not be destroyed or reshaped for the duration of the returned object,
      * care: the array must not be destroyed or reshaped for the duration of the returned object,
      * and the caller must take care not to access invalid dimensions or dimension indices.
      * and the caller must take care not to access invalid dimensions or dimension indices.
@@ -860,7 +867,8 @@ public:
         return array::mutable_unchecked<T, Dims>();
         return array::mutable_unchecked<T, Dims>();
     }
     }
 
 
-    /** Returns a proxy object that provides const access to the array's data without bounds or
+    /**
+     * Returns a proxy object that provides const access to the array's data without bounds or
      * dimensionality checking.  Unlike `unchecked()`, this does not require that the underlying
      * dimensionality checking.  Unlike `unchecked()`, this does not require that the underlying
      * array have the `writable` flag.  Use with care: the array must not be destroyed or reshaped
      * array have the `writable` flag.  Use with care: the array must not be destroyed or reshaped
      * for the duration of the returned object, and the caller must take care not to access invalid
      * for the duration of the returned object, and the caller must take care not to access invalid

include/pybind11/pybind11.h

@@ -1430,7 +1430,8 @@ void register_exception_translator(ExceptionTranslator&& translator) {
         std::forward<ExceptionTranslator>(translator));
         std::forward<ExceptionTranslator>(translator));
 }
 }
 
 
-/* Wrapper to generate a new Python exception type.
+/**
+ * Wrapper to generate a new Python exception type.
  *
  *
  * This should only be used with PyErr_SetString for now.
  * This should only be used with PyErr_SetString for now.
  * It is not (yet) possible to use as a py::base.
  * It is not (yet) possible to use as a py::base.
@@ -1455,7 +1456,8 @@ public:
     }
     }
 };
 };
 
 
-/** Registers a Python exception in `m` of the given `name` and installs an exception translator to
+/**
+ * Registers a Python exception in `m` of the given `name` and installs an exception translator to
  * translate the C++ exception to the created Python exception using the exceptions what() method.
  * translate the C++ exception to the created Python exception using the exceptions what() method.
  * This is intended for simple exception translations; for more complex translation, register the
  * This is intended for simple exception translations; for more complex translation, register the
  * exception object and translator directly.
  * exception object and translator directly.