From 37b2383a646c93f531ae4275c0957902b18afe03 Mon Sep 17 00:00:00 2001 From: Jason Rhinelander Date: Mon, 22 May 2017 12:06:16 -0400 Subject: [PATCH] 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 | 2 +- include/pybind11/cast.h | 2 +- include/pybind11/class_support.h | 3 ++- include/pybind11/numpy.h | 24 ++++++++++++++++-------- include/pybind11/pybind11.h | 6 ++++-- 5 files changed, 24 insertions(+), 13 deletions(-) diff --git a/include/pybind11/attr.h b/include/pybind11/attr.h index 608858183..84d2835c7 100644 --- a/include/pybind11/attr.h +++ b/include/pybind11/attr.h @@ -415,7 +415,7 @@ struct process_attribute : process_attribute_default {}; template struct process_attribute> : process_attribute_default> { }; -/*** +/** * 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 * otherwise diff --git a/include/pybind11/cast.h b/include/pybind11/cast.h index ace344ef1..bca4e85e3 100644 --- a/include/pybind11/cast.h +++ b/include/pybind11/cast.h @@ -34,7 +34,7 @@ struct type_info { std::vector *direct_conversions; buffer_info *(*get_buffer)(PyObject *, void *) = 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 */ bool simple_type : 1; /* True if there is no multiple inheritance in this type's inheritance tree */ diff --git a/include/pybind11/class_support.h b/include/pybind11/class_support.h index 995f57adf..55e623563 100644 --- a/include/pybind11/class_support.h +++ b/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 -/** 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, * 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. diff --git a/include/pybind11/numpy.h b/include/pybind11/numpy.h index 6e8b1be05..8901d9744 100644 --- a/include/pybind11/numpy.h +++ b/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(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()` method of `array` or the `unchecked()` method of `array_t`. `Dims` * will be -1 for dimensions determined at runtime. */ @@ -335,7 +336,8 @@ protected: : data_{reinterpret_cast(data)}, shape_{shape}, strides_{strides}, dims_{dims} {} 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 * 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"); return *reinterpret_cast(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)`. */ template > @@ -392,7 +395,8 @@ public: "Invalid number of indices for unchecked array reference"); return const_cast(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 * exactly equivalent to `obj(index)`. */ @@ -679,7 +683,8 @@ public: 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 * 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. @@ -691,7 +696,8 @@ public: return detail::unchecked_mutable_reference(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 * 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 @@ -851,7 +857,8 @@ public: return *(static_cast(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 * 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. @@ -860,7 +867,8 @@ public: return array::mutable_unchecked(); } - /** 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 * 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 diff --git a/include/pybind11/pybind11.h b/include/pybind11/pybind11.h index 4decfd1da..ca4b05894 100644 --- a/include/pybind11/pybind11.h +++ b/include/pybind11/pybind11.h @@ -1430,7 +1430,8 @@ void register_exception_translator(ExceptionTranslator&& translator) { std::forward(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. * 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. * This is intended for simple exception translations; for more complex translation, register the * exception object and translator directly.