Mercurial > octave
changeset 24624:ce2eb28e0a6d
doc: make all Doxygen comment blocks more consistent
* Array.h, dim-vector.h, gzip.cc, octave-link.h, octave-qt-link.h,
oct-parse.in.yy, oct-string.h, ov-base.h, ov.h, ovl.h, str-vec.h: Use uniform
C++ block commenting style consistent with the rest of Octave. Don't use
unnecessary @brief or @class markers. Use @-style commands instead of \-style.
| author | Mike Miller <mtmiller@octave.org> |
|---|---|
| date | Fri, 19 Jan 2018 19:59:28 -0800 |
| parents | f39ae754a7d8 |
| children | be37df6e1fb4 |
| files | libgui/src/octave-qt-link.h libinterp/corefcn/octave-link.h libinterp/dldfcn/gzip.cc libinterp/octave-value/ov-base.h libinterp/octave-value/ov.h libinterp/octave-value/ovl.h libinterp/parse-tree/oct-parse.in.yy liboctave/array/Array.h liboctave/array/dim-vector.h liboctave/util/oct-string.h liboctave/util/str-vec.h |
| diffstat | 11 files changed, 354 insertions(+), 371 deletions(-) [+] |
line wrap: on
line diff
--- a/libgui/src/octave-qt-link.h Fri Jan 19 15:09:42 2018 -0800 +++ b/libgui/src/octave-qt-link.h Fri Jan 19 19:59:28 2018 -0800 @@ -40,13 +40,12 @@ // Defined for purposes of sending QList<int> as part of signal. typedef QList<int> QIntList; -// @class OctaveLink -// @brief Provides threadsafe access to octave. -// @author Jacob Dawid -// -// This class is a wrapper around octave and provides thread safety by -// buffering access operations to octave and executing them in the -// readline event hook, which lives in the octave thread. +//! Provides threadsafe access to octave. +//! @author Jacob Dawid +//! +//! This class is a wrapper around octave and provides thread safety by +//! buffering access operations to octave and executing them in the +//! readline event hook, which lives in the octave thread. class octave_qt_link : public QObject, public octave_link {
--- a/libinterp/corefcn/octave-link.h Fri Jan 19 15:09:42 2018 -0800 +++ b/libinterp/corefcn/octave-link.h Fri Jan 19 19:59:28 2018 -0800 @@ -37,13 +37,12 @@ class string_vector; class workspace_element; -// \class OctaveLink -// \brief Provides threadsafe access to octave. -// \author Jacob Dawid -// -// This class is a wrapper around octave and provides thread safety by -// buffering access operations to octave and executing them in the -// readline event hook, which lives in the octave thread. +//! Provides threadsafe access to octave. +//! @author Jacob Dawid +//! +//! This class is a wrapper around octave and provides thread safety by +//! buffering access operations to octave and executing them in the +//! readline event hook, which lives in the octave thread. class OCTINTERP_API
--- a/libinterp/dldfcn/gzip.cc Fri Jan 19 15:09:42 2018 -0800 +++ b/libinterp/dldfcn/gzip.cc Fri Jan 19 19:59:28 2018 -0800 @@ -20,30 +20,29 @@ */ +//! @file gzip.cc //! Octave interface to the compression and uncompression libraries. -/*! - This was originally implemented as an m file which directly called - bzip2 and gzip applications. This may look simpler but causes some - issues (see bug #43431) because we have no control over the output - file: - - - created file is always in the same directory as the original file; - - automatically skip files that already have gz/bz2/etc extension; - - some older versions lack the --keep option. - - In addition, because system() does not have a method that allows - passing a list of arguments, there is the issue of having to escape - filenames. - - A solution is to pipe file contents into the applications instead of - filenames. However, that solution causes: - - # missing file header with original file information; - # implementing ourselves the recursive transversion of directories; - # do the above in a m file which will be slow; - # popen2 is frail on windows. - -*/ +//! +//! This was originally implemented as an m file which directly called +//! bzip2 and gzip applications. This may look simpler but causes some +//! issues (see bug #43431) because we have no control over the output +//! file: +//! +//! - created file is always in the same directory as the original file; +//! - automatically skip files that already have gz/bz2/etc extension; +//! - some older versions lack the --keep option. +//! +//! In addition, because system() does not have a method that allows +//! passing a list of arguments, there is the issue of having to escape +//! filenames. +//! +//! A solution is to pipe file contents into the applications instead of +//! filenames. However, that solution causes: +//! +//! # missing file header with original file information; +//! # implementing ourselves the recursive transversion of directories; +//! # do the above in a m file which will be slow; +//! # popen2 is frail on windows. #if defined (HAVE_CONFIG_H) # include "config.h" @@ -82,14 +81,14 @@ namespace octave { - //! RIIA wrapper for std::FILE* - /*! If error handling is available for failing to close the file, use - the close method which throws. - - If the file has been closed, fp is set to nullptr. Remember that - behavior is undefined if the value of the pointer stream is used - after fclose. - */ + //! RIIA wrapper for std::FILE*. + //! + //! If error handling is available for failing to close the file, use + //! the close method which throws. + //! + //! If the file has been closed, fp is set to nullptr. Remember that + //! behavior is undefined if the value of the pointer stream is used + //! after fclose. class CFile {
--- a/libinterp/octave-value/ov-base.h Fri Jan 19 15:09:42 2018 -0800 +++ b/libinterp/octave-value/ov-base.h Fri Jan 19 19:59:28 2018 -0800 @@ -105,20 +105,19 @@ inline bool btyp_isarray (builtin_type_t btyp) { return btyp <= btyp_char; } -/*! - * \brief Determine the resulting type for a possible mixed-type operation. - * - * Rules for the resulting type: - * - bool -> double - * - single + double -> single - * - real + complex -> complex - * - integer + real -> integer - * - uint + uint -> uint (the bigger one) - * - sint + sint -> sint (the bigger one) - * - * \return The resulting type or "unknown type", if the resulting type cannot - * be determined. - */ +//! Determine the resulting type for a possible mixed-type operation. +//! +//! Rules for the resulting type: +//! - bool -> double +//! - single + double -> single +//! - real + complex -> complex +//! - integer + real -> integer +//! - uint + uint -> uint (the bigger one) +//! - sint + sint -> sint (the bigger one) +//! +//! @return The resulting type or "unknown type", if the resulting type cannot +//! be determined. + extern OCTINTERP_API builtin_type_t btyp_mixed_numeric (builtin_type_t x, builtin_type_t y);
--- a/libinterp/octave-value/ov.h Fri Jan 19 15:09:42 2018 -0800 +++ b/libinterp/octave-value/ov.h Fri Jan 19 19:59:28 2018 -0800 @@ -1464,27 +1464,25 @@ octave_value map (octave_base_value::unary_mapper_t umap) const { return rep->map (umap); } - /*! - * \brief Extract the n-th element, aka `val(n)`. - * - * \return Result is undefined if `val` is not an array type - * or \p n is out of range. - * - * \warning Function calls should never error. - */ + //! Extract the n-th element, aka `val(n)`. + //! + //! @return Result is undefined if `val` is not an array type + //! or @p n is out of range. + //! + //! @warning Function calls should never error. + octave_value fast_elem_extract (octave_idx_type n) const { return rep->fast_elem_extract (n); } - /*! - * \brief Assign the n-th element, aka `val(n) = x`. - * - * \returns false if `val` is not an array type, - * \p x is not a matching scalar type, - * or \p n is out of range. - * - * \warning Function calls should never error. - */ + //! Assign the n-th element, aka `val(n) = x`. + //! + //! @returns false if `val` is not an array type, + //! @p x is not a matching scalar type, + //! or @p n is out of range. + //! + //! @warning Function calls should never error. + bool fast_elem_insert (octave_idx_type n, const octave_value& x) {
--- a/libinterp/octave-value/ovl.h Fri Jan 19 15:09:42 2018 -0800 +++ b/libinterp/octave-value/ovl.h Fri Jan 19 19:59:28 2018 -0800 @@ -174,17 +174,17 @@ //! Construct an octave_value_list with less typing. -/*! - Historically, this made it easier to create an octave_value_list - from multiple octave_value arguments. It is no longer useful since - octave_value_list has now a constructor accepting an initializer_list - so all it does is save some typing. The following are equivalent: +//! +//! Historically, this made it easier to create an octave_value_list +//! from multiple octave_value arguments. It is no longer useful since +//! octave_value_list has now a constructor accepting an initializer_list +//! so all it does is save some typing. The following are equivalent: +//! +//! @code{.cc} +//! return octave_value_list ({ov0, ov1, ov2}); +//! return ovl (ov0, ov1, ov2); +//! @endcode - @code{.cc} - return octave_value_list ({ov0, ov1, ov2}); - return ovl (ov0, ov1, ov2); - @endcode -*/ template<typename... OV_Args> inline octave_value_list ovl (const OV_Args&... args)
--- a/libinterp/parse-tree/oct-parse.in.yy Fri Jan 19 15:09:42 2018 -0800 +++ b/libinterp/parse-tree/oct-parse.in.yy Fri Jan 19 19:59:28 2018 -0800 @@ -5177,17 +5177,15 @@ namespace octave { - /*! - Evaluate an Octave function (built-in or interpreted) and return - the list of result values. - - @param name The name of the function to call. - @param args The arguments to the function. - @param nargout The number of output arguments expected. - @return A list of output values. The length of the list is not - necessarily the same as @c nargout. - - */ + //! Evaluate an Octave function (built-in or interpreted) and return + //! the list of result values. + //! + //! @param name The name of the function to call. + //! @param args The arguments to the function. + //! @param nargout The number of output arguments expected. + //! @return A list of output values. The length of the list is not + //! necessarily the same as @c nargout. + octave_value_list feval (const std::string& name, const octave_value_list& args, int nargout) { @@ -5262,18 +5260,17 @@ namespace octave { - /*! - Evaluate an Octave function (built-in or interpreted) and return - the list of result values. - - @param args The first element of @c args is the function to call. - It may be the name of the function as a string, a function - handle, or an inline function. The remaining arguments are - passed to the function. - @param nargout The number of output arguments expected. - @return A list of output values. The length of the list is not - necessarily the same as @c nargout. - */ + //! Evaluate an Octave function (built-in or interpreted) and return + //! the list of result values. + //! + //! @param args The first element of @c args is the function to call. + //! It may be the name of the function as a string, a function + //! handle, or an inline function. The remaining arguments are + //! passed to the function. + //! @param nargout The number of output arguments expected. + //! @return A list of output values. The length of the list is not + //! necessarily the same as @c nargout. + octave_value_list feval (const octave_value_list& args, int nargout) {
--- a/liboctave/array/Array.h Fri Jan 19 15:09:42 2018 -0800 +++ b/liboctave/array/Array.h Fri Jan 19 19:59:28 2018 -0800 @@ -44,84 +44,83 @@ #include "quit.h" //! N Dimensional Array with copy-on-write semantics. -/*! - The Array class is at the root of Octave. It provides a container - with an arbitrary number of dimensions. The operator () provides - access to individual elements via subscript and linear indexing. - Indexing starts at 0. Arrays are column-major order as in Fortran. - - @code{.cc} - // 3 D Array with 10 rows, 20 columns, and 5 pages, filled with 7.0 - Array<double> A Array<double (dim_vector (10, 20, 5), 7.0); - - // set value for row 0, column 10, and page 3 - A(0, 10, 3) = 2.5; - - // get value for row 1, column 2, and page 0 - double v = A(1, 2, 0); - - // get value for 25th element (row 4, column 3, page 1) - double v = A(24); - @endcode - - ## Notes on STL compatibility - - ### size() and length() - - To access the total number of elements in an Array, use numel() - which is short for number of elements and is equivalent to the - Octave function with same name. - - @code{.cc} - Array<int> A (dim_vector (10, 20, 4), 1); - - octave_idx_type n = A.numel (); // returns 800 (10x20x4) - - octave_idx_type nr = A.size (0); // returns 10 (number of rows/dimension 0) - octave_idx_type nc = A.size (1); // returns 20 (number of columns) - octave_idx_type nc = A.size (2); // returns 4 (size of dimension 3) - octave_idx_type l6 = A.size (6); // returns 1 (implicit singleton dimension) +//! +//! The Array class is at the root of Octave. It provides a container +//! with an arbitrary number of dimensions. The operator () provides +//! access to individual elements via subscript and linear indexing. +//! Indexing starts at 0. Arrays are column-major order as in Fortran. +//! +//! @code{.cc} +//! // 3 D Array with 10 rows, 20 columns, and 5 pages, filled with 7.0 +//! Array<double> A Array<double (dim_vector (10, 20, 5), 7.0); +//! +//! // set value for row 0, column 10, and page 3 +//! A(0, 10, 3) = 2.5; +//! +//! // get value for row 1, column 2, and page 0 +//! double v = A(1, 2, 0); +//! +//! // get value for 25th element (row 4, column 3, page 1) +//! double v = A(24); +//! @endcode +//! +//! ## Notes on STL compatibility +//! +//! ### size() and length() +//! +//! To access the total number of elements in an Array, use numel() +//! which is short for number of elements and is equivalent to the +//! Octave function with same name. +//! +//! @code{.cc} +//! Array<int> A (dim_vector (10, 20, 4), 1); +//! +//! octave_idx_type n = A.numel (); // returns 800 (10x20x4) +//! +//! octave_idx_type nr = A.size (0); // returns 10 (number of rows/dimension 0) +//! octave_idx_type nc = A.size (1); // returns 20 (number of columns) +//! octave_idx_type nc = A.size (2); // returns 4 (size of dimension 3) +//! octave_idx_type l6 = A.size (6); // returns 1 (implicit singleton dimension) +//! +//! // Alternatively, get a dim_vector which represents the dimensions. +//! dim_vector dims = A.dims (); +//! @endcode +//! +//! The methods size() and length() as they exist in the STL cause +//! confusion in the context of a N dimensional array. +//! +//! The size() of an array is the length of all dimensions. In Octave, +//! the size() function returns a row vector with the length of each +//! dimension, or the size of a specific dimension. Only the latter is +//! present in liboctave. +//! +//! Since there is more than 1 dimension, length() would not make sense +//! without expliciting which dimension. If the function existed, which +//! length should it return? Octave length() function returns the length +//! of the longest dimension which is an odd definition, only useful for +//! vectors and square matrices. The alternatives numel(), rows(), +//! columns(), and size(d) are more explict and recommended. +//! +//! ### size_type +//! +//! Array::size_type is `octave_idx_type` which is a typedef for `int` +//! or `long int`, depending whether Octave was configured for 64-bit +//! indexing. +//! +//! This is a signed integer which may cause problems when mixed with +//! STL containers. The reason is that Octave interacts with Fortran +//! routines, providing an interface many Fortran numeric libraries. +//! +//! ## Subclasses +//! +//! The following subclasses specializations, will be of most use: +//! - Matrix: Array<double> with only 2 dimensions +//! - ComplexMatrix: Array<std::complex<double>> with only 2 dimensions +//! - boolNDArray: N dimensional Array<bool> +//! - ColumnVector: Array<double> with 1 column +//! - string_vector: Array<std::string> with 1 column +//! - Cell: Array<octave_value>, equivalent to an Octave cell. - // Alternatively, get a dim_vector which represents the dimensions. - dim_vector dims = A.dims (); - @endcode - - The methods size() and length() as they exist in the STL cause - confusion in the context of a N dimensional array. - - The size() of an array is the length of all dimensions. In Octave, - the size() function returns a row vector with the length of each - dimension, or the size of a specific dimension. Only the latter is - present in liboctave. - - Since there is more than 1 dimension, length() would not make sense - without expliciting which dimension. If the function existed, which - length should it return? Octave length() function returns the length - of the longest dimension which is an odd definition, only useful for - vectors and square matrices. The alternatives numel(), rows(), - columns(), and size(d) are more explict and recommended. - - ### size_type - - Array::size_type is `octave_idx_type` which is a typedef for `int` - or `long int`, depending whether Octave was configured for 64-bit - indexing. - - This is a signed integer which may cause problems when mixed with - STL containers. The reason is that Octave interacts with Fortran - routines, providing an interface many Fortran numeric libraries. - - ## Subclasses - - The following subclasses specializations, will be of most use: - - Matrix: Array<double> with only 2 dimensions - - ComplexMatrix: Array<std::complex<double>> with only 2 dimensions - - boolNDArray: N dimensional Array<bool> - - ColumnVector: Array<double> with 1 column - - string_vector: Array<std::string> with 1 column - - Cell: Array<octave_value>, equivalent to an Octave cell. - -*/ template <typename T> class Array @@ -344,15 +343,16 @@ octave_idx_type capacity (void) const { return numel (); } //! Number of elements in the array. - /*! Synonymous with numel(). - @note This method is deprecated in favour of numel(). + //! + //! Synonymous with numel(). + //! @note This method is deprecated in favour of numel(). + //! + //! @note + //! This is @em not the same as @c %length() at the Octave interpreter. + //! At the Octave interpreter, the function @c %length() returns the + //! length of the greatest dimension. This method returns the total + //! number of elements. - @note - This is @em not the same as @c %length() at the Octave interpreter. - At the Octave interpreter, the function @c %length() returns the - length of the greatest dimension. This method returns the total - number of elements. - */ OCTAVE_DEPRECATED (4.4, "use 'numel' instead") octave_idx_type length (void) const { return numel (); } @@ -422,12 +422,12 @@ //@} //! Size of the specified dimension. - /*! - Dimensions beyond the Array number of dimensions return 1 as - those are implicit singleton dimensions. + //! + //! Dimensions beyond the Array number of dimensions return 1 as + //! those are implicit singleton dimensions. + //! + //! Equivalent to Octave's `size (A, DIM)` - Equivalent to Octave's `size (A, DIM)` - */ size_type size (const size_type d) const { // Should we throw for negative values? @@ -722,7 +722,7 @@ //! Ordering is auto-detected or can be specified. sortmode is_sorted_rows (sortmode mode = UNSORTED) const; - //! @brief Do a binary lookup in a sorted array. Must not contain NaNs. + //! Do a binary lookup in a sorted array. Must not contain NaNs. //! Mode can be specified or is auto-detected by comparing 1st and last element. octave_idx_type lookup (const T& value, sortmode mode = UNSORTED) const;
--- a/liboctave/array/dim-vector.h Fri Jan 19 15:09:42 2018 -0800 +++ b/liboctave/array/dim-vector.h Fri Jan 19 19:59:28 2018 -0800 @@ -37,53 +37,52 @@ template <typename T> class Array; //! Vector representing the dimensions (size) of an Array. -/*! - A dim_vector is used to represent dimensions of an Array. It is used - on its constructor to specify its size, or when reshaping it. - - @code{.cc} - // Matrix with 10 rows and 20 columns. - Matrix m Matrix (dim_vector (10, 20)); - - // Change its size to 5 rows and 40 columns. - Matrix m2 = m.reshape (dim_vector (5, 40)); - - // Five dimensional Array of length 10, 20, 3, 8, 7 on each dimension. - NDArray a (dim_vector (10, 20, 3, 8, 7)); - - // Uninitialized array of same size as other. - NDArray b (a.dims ()); - @endcode - - The main thing to understand about this class, is that methods such as - ndims() and numel(), return the value for an Array of these dimensions, - not the actual number of elements in the dim_vector. - - @code{.cc} - dim_vector d (10, 5, 3); - octave_idx_type n = d.numel (); // returns 150 - octave_idx_type nd = d.ndims (); // returns 3 - @endcode - - ## Implementation details ## - - This implementation is more tricky than Array, but the big plus is that - dim_vector requires only one allocation instead of two. It is (slightly) - patterned after GCC's basic_string implementation. rep is a pointer to an - array of memory, comprising count, length, and the data: - - @verbatim - <count> - <ndims> - rep --> <dims[0]> - <dims[1]> - ... - @endverbatim - - The inlines count(), ndims() recover this data from the rep. Note - that rep points to the beginning of dims to grant faster access - (reinterpret_cast is assumed to be an inexpensive operation). -*/ +//! +//! A dim_vector is used to represent dimensions of an Array. It is used +//! on its constructor to specify its size, or when reshaping it. +//! +//! @code{.cc} +//! // Matrix with 10 rows and 20 columns. +//! Matrix m Matrix (dim_vector (10, 20)); +//! +//! // Change its size to 5 rows and 40 columns. +//! Matrix m2 = m.reshape (dim_vector (5, 40)); +//! +//! // Five dimensional Array of length 10, 20, 3, 8, 7 on each dimension. +//! NDArray a (dim_vector (10, 20, 3, 8, 7)); +//! +//! // Uninitialized array of same size as other. +//! NDArray b (a.dims ()); +//! @endcode +//! +//! The main thing to understand about this class, is that methods such as +//! ndims() and numel(), return the value for an Array of these dimensions, +//! not the actual number of elements in the dim_vector. +//! +//! @code{.cc} +//! dim_vector d (10, 5, 3); +//! octave_idx_type n = d.numel (); // returns 150 +//! octave_idx_type nd = d.ndims (); // returns 3 +//! @endcode +//! +//! ## Implementation details ## +//! +//! This implementation is more tricky than Array, but the big plus is that +//! dim_vector requires only one allocation instead of two. It is (slightly) +//! patterned after GCC's basic_string implementation. rep is a pointer to an +//! array of memory, comprising count, length, and the data: +//! +//! @verbatim +//! <count> +//! <ndims> +//! rep --> <dims[0]> +//! <dims[1]> +//! ... +//! @endverbatim +//! +//! The inlines count(), ndims() recover this data from the rep. Note +//! that rep points to the beginning of dims to grant faster access +//! (reinterpret_cast is assumed to be an inexpensive operation). class OCTAVE_API @@ -164,41 +163,40 @@ public: //! Construct dim_vector for a N dimensional array. - /*! - - Each argument to constructor defines the length of an additional - dimension. A dim_vector always represents a minimum of 2 dimensions - (just like an Array has at least 2 dimensions) and there is no - upper limit on the number of dimensions. - - @code{.cc} - dim_vector dv (7, 5); - Matrix mat (dv); - @endcode - - The constructed dim_vector @c dv will have two elements, @f$[7, 5]@f$, - one for each dimension. It can then be used to construct a Matrix - with such dimensions, i.e., 7 rows and 5 columns. + //! + //! Each argument to constructor defines the length of an additional + //! dimension. A dim_vector always represents a minimum of 2 dimensions + //! (just like an Array has at least 2 dimensions) and there is no + //! upper limit on the number of dimensions. + //! + //! @code{.cc} + //! dim_vector dv (7, 5); + //! Matrix mat (dv); + //! @endcode + //! + //! The constructed dim_vector @c dv will have two elements, @f$[7, 5]@f$, + //! one for each dimension. It can then be used to construct a Matrix + //! with such dimensions, i.e., 7 rows and 5 columns. + //! + //! @code{.cc} + //! NDArray x (dim_vector (7, 5, 10)); + //! @endcode + //! + //! This will construct a 3 dimensional NDArray of lengths 7, 5, and 10, + //! on the first, second, and third dimension (rows, columns, and pages) + //! respectively. + //! + //! Note that that there is no constructor that accepts only one + //! dimension length to avoid confusion. The source for such confusion + //! is that constructor could mean: + //! - a column vector, i.e., assume @f$[N, 1]@f$; + //! - a square matrix, i.e., as is common in Octave interpreter; + //! - support for a 1 dimensional Array (does not exist); + //! + //! Using r, c, and lengths... as arguments, allow us to check at compile + //! time that there's at least 2 dimensions specified, while maintaining + //! type safety. - @code{.cc} - NDArray x (dim_vector (7, 5, 10)); - @endcode - - This will construct a 3 dimensional NDArray of lengths 7, 5, and 10, - on the first, second, and third dimension (rows, columns, and pages) - respectively. - - Note that that there is no constructor that accepts only one - dimension length to avoid confusion. The source for such confusion - is that constructor could mean: - - a column vector, i.e., assume @f$[N, 1]@f$; - - a square matrix, i.e., as is common in Octave interpreter; - - support for a 1 dimensional Array (does not exist); - - Using r, c, and lengths... as arguments, allow us to check at compile - time that there's at least 2 dimensions specified, while maintaining - type safety. - */ template <typename... Ints> dim_vector (const octave_idx_type r, const octave_idx_type c, Ints... lengths) : rep (newrep (2 + sizeof... (Ints))) @@ -289,20 +287,20 @@ } //! Number of dimensions. - /*! - Returns the number of dimensions of the dim_vector. This is number of - elements in the dim_vector including trailing singletons. It is also - the number of dimensions an Array with this dim_vector would have. - */ + //! + //! Returns the number of dimensions of the dim_vector. This is number of + //! elements in the dim_vector including trailing singletons. It is also + //! the number of dimensions an Array with this dim_vector would have. + octave_idx_type ndims (void) const { return rep[-1]; } //! Number of dimensions. //! Synonymous with ndims(). - /*! - While this method is not officially deprecated, consider using ndims() - instead to avoid confusion. Array does not have length because of its - odd definition as length of the longest dimension. - */ + //! + //! While this method is not officially deprecated, consider using ndims() + //! instead to avoid confusion. Array does not have length because of its + //! odd definition as length of the longest dimension. + int length (void) const { return ndims (); } octave_idx_type& operator () (int i) { return elem (i); } @@ -356,11 +354,10 @@ } //! Number of elements that a matrix with this dimensions would have. - /*! - Return the number of elements that a matrix with this dimension - vector would have, NOT the number of dimensions (elements in the - dimension vector). - */ + //! + //! Return the number of elements that a matrix with this dimension + //! vector would have, NOT the number of dimensions (elements in the + //! dimension vector). octave_idx_type numel (int n = 0) const { @@ -374,15 +371,13 @@ return retval; } - /*! - The following function will throw a std::bad_alloc () - exception if the requested size is larger than can be indexed by - octave_idx_type. This may be smaller than the actual amount of - memory that can be safely allocated on a system. However, if we - don't fail here, we can end up with a mysterious crash inside a - function that is iterating over an array using octave_idx_type - indices. - */ + //! The following function will throw a std::bad_alloc () + //! exception if the requested size is larger than can be indexed by + //! octave_idx_type. This may be smaller than the actual amount of + //! memory that can be safely allocated on a system. However, if we + //! don't fail here, we can end up with a mysterious crash inside a + //! function that is iterating over an array using octave_idx_type + //! indices. octave_idx_type safe_numel (void) const; @@ -401,12 +396,11 @@ // The rules are more relaxed here. bool hvcat (const dim_vector& dvb, int dim); - /*! - Force certain dimensionality, preserving numel (). Missing - dimensions are set to 1, redundant are folded into the trailing - one. If n = 1, the result is 2d and the second dim is 1 - (dim_vectors are always at least 2D). - */ + //! Force certain dimensionality, preserving numel (). Missing + //! dimensions are set to 1, redundant are folded into the trailing + //! one. If n = 1, the result is 2d and the second dim is 1 + //! (dim_vectors are always at least 2D). + dim_vector redim (int n) const; dim_vector as_column (void) const @@ -503,11 +497,9 @@ return k; } - /*/! - Increment a multi-dimensional index tuple, optionally starting - from an offset position and return the index of the last index - position that was changed, or length () if just cycled over. - */ + //! Increment a multi-dimensional index tuple, optionally starting + //! from an offset position and return the index of the last index + //! position that was changed, or length () if just cycled over. int increment_index (octave_idx_type *idx, int start = 0) const {
--- a/liboctave/util/oct-string.h Fri Jan 19 15:09:42 2018 -0800 +++ b/liboctave/util/oct-string.h Fri Jan 19 19:59:28 2018 -0800 @@ -27,74 +27,74 @@ namespace octave { //! Octave string utility functions. - /*! - This functions provide a C++ interface to most string functions - available in the Octave interpreter. - - Specializations for Array may consider its dimensions in addition - to the actual string contents. + //! + //! This functions provide a C++ interface to most string functions + //! available in the Octave interpreter. + //! + //! Specializations for Array may consider its dimensions in addition + //! to the actual string contents. + //! + //! @attention + //! Octave's string comparison functions return true when strings are + //! are equal, just the opposite of the corresponding C library functions. + //! In addition, Octave's function only return bool and do not check + //! lexicographical order. - @attention - Octave's string comparison functions return true when strings are - are equal, just the opposite of the corresponding C library functions. - In addition, Octave's function only return bool and do not check - lexicographical order. - */ namespace string { //! True if strings are the same. - /*! - ## Specialization for Array<char> + //! + //! ## Specialization for Array<char> + //! + //! When comparing whole Array of chars, the actual Array dimensions + //! are significant. A column vector and row vector with the same + //! char array, will still return false. - When comparing whole Array of chars, the actual Array dimensions - are significant. A column vector and row vector with the same - char array, will still return false. - */ template <typename T> bool strcmp (const T& str_a, const T& str_b); //! True if string is the same as character sequence. - /*! - Compares a string to the null-terminated character sequence - beginning at the character pointed to by str_b. + //! + //! Compares a string to the null-terminated character sequence + //! beginning at the character pointed to by str_b. + //! + //! ## Specialization for Array<char> + //! + //! For purposes of comparison of dimensions, the character sequence + //! is considered to be a row vector. - ## Specialization for Array<char> - - For purposes of comparison of dimensions, the character sequence - is considered to be a row vector. - */ template <typename T> bool strcmp (const T& str_a, const typename T::value_type *str_b); //! True if strings are the same, ignoring case. - /*! - ## Specialization for Array<char> + //! + //! ## Specialization for Array<char> + //! + //! When comparing whole Array of chars, the actual Array dimensions + //! are significant. A column vector and row vector with the same + //! char array, will still return false. - When comparing whole Array of chars, the actual Array dimensions - are significant. A column vector and row vector with the same - char array, will still return false. - */ template <typename T> bool strcmpi (const T& str_a, const T& str_b); //! True if string is the same as character sequence, ignoring case. - /*! - ## Specialization for Array<char> + //! + //! ## Specialization for Array<char> + //! + //! For purposes of comparison of dimensions, the character sequence + //! is considered to be a row vector. - For purposes of comparison of dimensions, the character sequence - is considered to be a row vector. - */ template <typename T> bool strcmpi (const T& str_a, const typename T::value_type *str_b); //! True if the first N characters are the same. - /*! - ## Specialization for Array<char> + //! + //! ## Specialization for Array<char> + //! + //! The comparison is done in the first N characters, the actual + //! dimensions of the Array are irrelevant. A row vector and + //! a column vector of the same still return true. - The comparison is done in the first N characters, the actual - dimensions of the Array are irrelevant. A row vector and - a column vector of the same still return true. - */ template <typename T> bool strncmp (const T& str_a, const T& str_b, const typename T::size_type n); @@ -105,13 +105,13 @@ const typename T::size_type n); //! True if the first N characters are the same, ignoring case. - /*! - ## Specialization for Array<char> + //! + //! ## Specialization for Array<char> + //! + //! The comparison is done in the first N characters, the actual + //! dimensions of the Array are irrelevant. A row vector and + //! a column vector of the same still return true. - The comparison is done in the first N characters, the actual - dimensions of the Array are irrelevant. A row vector and - a column vector of the same still return true. - */ template <typename T> bool strncmpi (const T& str_a, const T& str_b, const typename T::size_type n);
--- a/liboctave/util/str-vec.h Fri Jan 19 15:09:42 2018 -0800 +++ b/liboctave/util/str-vec.h Fri Jan 19 19:59:28 2018 -0800 @@ -50,12 +50,12 @@ string_vector (const string_vector& s) : Array<std::string> (s) { } - //! Constructor for STL containers of std::string - /*! - Templated constructor for any template class with std::string as the - first parameter, and begin, end, and size methods, i.e., a class with - similar interface as the STL containers. - */ + //! Constructor for STL containers of std::string. + //! + //! Templated constructor for any template class with std::string as the + //! first parameter, and begin, end, and size methods, i.e., a class with + //! similar interface as the STL containers. + template<template <typename...> class String_Container, typename... Other> string_vector (const String_Container<std::string, Other...>& lst);