# HG changeset patch # User Jordi Gutiérrez Hermoso # Date 1407871636 14400 # Node ID 96751a74bbbb31f15597c48687d8465dc2036f2d # Parent d00f6b09258fa5632ff45aa345bf6594d9f232a8 Start doxygenising sources * Screen.cpp Screen.h Vt102Emulation.cpp files-dock-widget.h main-window.h octave-qt-link.h parser.h: Reformat existing Doxygen commands to use @ instead of \ to start a command. * Array.h: Convert existing comments into Doxygen comments. diff -r d00f6b09258f -r 96751a74bbbb libgui/qterminal/libqterminal/unix/Screen.cpp --- a/libgui/qterminal/libqterminal/unix/Screen.cpp Mon Aug 11 09:39:45 2014 -0700 +++ b/libgui/qterminal/libqterminal/unix/Screen.cpp Tue Aug 12 15:27:16 2014 -0400 @@ -110,7 +110,7 @@ // Cursor Setting -------------------------------------------------------------- -/*! \section Cursor +/*! @section Cursor The `cursor' is a location within the screen that is implicitely used in many operations. The operations within this section allow to manipulate @@ -502,7 +502,7 @@ /*! returns the image. - Get the size of the image by \sa getLines and \sa getColumns. + Get the size of the image by @sa getLines and @sa getColumns. NOTE that the image returned by this function must later be freed. @@ -861,7 +861,7 @@ /*! scroll up `n' lines within current region. The `n' new lines are cleared. - \sa setRegion \sa scrollDown + @sa setRegion @sa scrollDown */ QRect Screen::lastScrolledRegion() const @@ -889,7 +889,7 @@ /*! scroll down `n' lines within current region. The `n' new lines are cleared. - \sa setRegion \sa scrollUp + @sa setRegion @sa scrollUp */ void Screen::scrollDown(int from, int n) @@ -949,7 +949,7 @@ // Erasing --------------------------------------------------------------------- -/*! \section Erasing +/*! @section Erasing This group of operations erase parts of the screen contents by filling it with spaces colored due to the current rendition settings. diff -r d00f6b09258f -r 96751a74bbbb libgui/qterminal/libqterminal/unix/Screen.h --- a/libgui/qterminal/libqterminal/unix/Screen.h Mon Aug 11 09:39:45 2014 -0700 +++ b/libgui/qterminal/libqterminal/unix/Screen.h Tue Aug 12 15:27:16 2014 -0400 @@ -50,7 +50,7 @@ class TerminalCharacterDecoder; /** - \brief An image of characters with associated attributes. + @brief An image of characters with associated attributes. The terminal emulation ( Emulation ) receives a serial stream of characters from the program currently running in the terminal. diff -r d00f6b09258f -r 96751a74bbbb libgui/qterminal/libqterminal/unix/Vt102Emulation.cpp --- a/libgui/qterminal/libqterminal/unix/Vt102Emulation.cpp Mon Aug 11 09:39:45 2014 -0700 +++ b/libgui/qterminal/libqterminal/unix/Vt102Emulation.cpp Tue Aug 12 15:27:16 2014 -0400 @@ -1221,10 +1221,10 @@ /*! shows the contents of the scan buffer. - This functions is used for diagnostics. It is called by \e ReportErrorToken + This functions is used for diagnostics. It is called by @e ReportErrorToken to inform about strings that cannot be decoded or handled by the emulation. - \sa ReportErrorToken + @sa ReportErrorToken */ static void hexdump(int* s, int len) diff -r d00f6b09258f -r 96751a74bbbb libgui/src/files-dock-widget.h --- a/libgui/src/files-dock-widget.h Mon Aug 11 09:39:45 2014 -0700 +++ b/libgui/src/files-dock-widget.h Tue Aug 12 15:27:16 2014 -0400 @@ -40,8 +40,8 @@ #include "octave-dock-widget.h" /** - \class files_dock_widget - \brief Dock widget to display files in the current directory. + @class files_dock_widget + @brief Dock widget to display files in the current directory. */ class files_dock_widget : public octave_dock_widget { diff -r d00f6b09258f -r 96751a74bbbb libgui/src/main-window.h --- a/libgui/src/main-window.h Mon Aug 11 09:39:45 2014 -0700 +++ b/libgui/src/main-window.h Tue Aug 12 15:27:16 2014 -0400 @@ -58,7 +58,7 @@ #include "find-files-dialog.h" /** - * \class MainWindow + * @class MainWindow * * Represents the main window. */ diff -r d00f6b09258f -r 96751a74bbbb libgui/src/octave-qt-link.h --- a/libgui/src/octave-qt-link.h Mon Aug 11 09:39:45 2014 -0700 +++ b/libgui/src/octave-qt-link.h Tue Aug 12 15:27:16 2014 -0400 @@ -39,9 +39,9 @@ // Defined for purposes of sending QList as part of signal. typedef QList QIntList; -// \class OctaveLink -// \brief Provides threadsafe access to octave. -// \author Jacob Dawid +// @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 diff -r d00f6b09258f -r 96751a74bbbb libgui/src/qtinfo/parser.h --- a/libgui/src/qtinfo/parser.h Mon Aug 11 09:39:45 2014 -0700 +++ b/libgui/src/qtinfo/parser.h Tue Aug 12 15:27:16 2014 -0400 @@ -30,7 +30,7 @@ #include /** - * \class parser + * @class parser * This class gets nodes and searchs inside of 'info files'. *

Each info file has nodes. Every node has the documentation. * Info files contains a map with position of each node.

@@ -103,9 +103,9 @@ QIODevice *open_file(QFileInfo & fileInfo); /** Calculates real position of nodes. - * \param pos position from info file. - * \param fileInfo returns file what contains that position. - * \param realPos returns real position inside of fileInfo. + * @param pos position from info file. + * @param fileInfo returns file what contains that position. + * @param realPos returns real position inside of fileInfo. */ void real_position (int pos, QFileInfo & file_info, int & real_pos); diff -r d00f6b09258f -r 96751a74bbbb liboctave/array/Array.h --- a/liboctave/array/Array.h Mon Aug 11 09:39:45 2014 -0700 +++ b/liboctave/array/Array.h Tue Aug 12 15:27:16 2014 -0400 @@ -41,8 +41,8 @@ #include "oct-mem.h" #include "oct-refcount.h" -// One dimensional array class. Handles the reference counting for -// all the derived classes. +//! One dimensional array class. Handles the reference counting for +//! all the derived classes. template class @@ -50,10 +50,7 @@ { protected: - //-------------------------------------------------------------------- - // The real representation of all arrays. - //-------------------------------------------------------------------- - + //! The real representation of all arrays. class ArrayRep { public: @@ -144,7 +141,7 @@ T* slice_data; octave_idx_type slice_len; - // slice constructor + //! slice constructor Array (const Array& a, const dim_vector& dv, octave_idx_type l, octave_idx_type u) : dimensions (dv), rep(a.rep), slice_data (a.slice_data+l), slice_len (u-l) @@ -167,7 +164,7 @@ protected: - // For jit support + //! For jit support Array (T *sdata, octave_idx_type slen, octave_idx_type *adims, void *arep) : dimensions (adims), rep (reinterpret_cast::ArrayRep *> (arep)), @@ -175,8 +172,7 @@ public: - // Empty ctor (0x0). - + //! Empty ctor (0 by 0). Array (void) : dimensions (), rep (nil_rep ()), slice_data (rep->data), slice_len (rep->len) @@ -184,13 +180,13 @@ rep->count++; } - // Obsolete 1D ctor (there are no 1D arrays). + //! Obsolete 1D ctor (there are no 1D arrays). explicit Array (octave_idx_type n) GCC_ATTR_DEPRECATED : dimensions (n, 1), rep (new typename Array::ArrayRep (n)), slice_data (rep->data), slice_len (rep->len) { } - // Obsolete initialized 1D ctor (there are no 1D arrays). + //! Obsolete initialized 1D ctor (there are no 1D arrays). explicit Array (octave_idx_type n, const T& val) GCC_ATTR_DEPRECATED : dimensions (n, 1), rep (new typename Array::ArrayRep (n)), slice_data (rep->data), slice_len (rep->len) @@ -198,7 +194,7 @@ fill (val); } - // nD uninitialized ctor. + //! nD uninitialized ctor. explicit Array (const dim_vector& dv) : dimensions (dv), rep (new typename Array::ArrayRep (dv.safe_numel ())), @@ -207,7 +203,7 @@ dimensions.chop_trailing_singletons (); } - // nD initialized ctor. + //! nD initialized ctor. explicit Array (const dim_vector& dv, const T& val) : dimensions (dv), rep (new typename Array::ArrayRep (dv.safe_numel ())), @@ -217,10 +213,10 @@ dimensions.chop_trailing_singletons (); } - // Reshape constructor. + //! Reshape constructor. Array (const Array& a, const dim_vector& dv); - // Type conversion case. + //! Type conversion case. template Array (const Array& a) : dimensions (a.dims ()), @@ -228,7 +224,7 @@ slice_data (rep->data), slice_len (rep->len) { } - // No type conversion case. + //! No type conversion case. Array (const Array& a) : dimensions (a.dimensions), rep (a.rep), slice_data (a.slice_data), slice_len (a.slice_len) @@ -270,16 +266,15 @@ void clear (octave_idx_type r, octave_idx_type c) { clear (dim_vector (r, c)); } + //@{ + //! Number of elements in the array. These are all synonyms. octave_idx_type capacity (void) const { return slice_len; } octave_idx_type length (void) const { return capacity (); } octave_idx_type nelem (void) const { return capacity (); } octave_idx_type numel (void) const { return nelem (); } + //@} - octave_idx_type dim1 (void) const { return dimensions(0); } - octave_idx_type dim2 (void) const { return dimensions(1); } - octave_idx_type dim3 (void) const { return dimensions(2); } - - // Return the array as a column vector. + //! Return the array as a column vector. Array as_column (void) const { Array retval (*this); @@ -289,7 +284,7 @@ return retval; } - // Return the array as a row vector. + //! Return the array as a row vector. Array as_row (void) const { Array retval (*this); @@ -299,7 +294,7 @@ return retval; } - // Return the array as a matrix. + //! Return the array as a matrix. Array as_matrix (void) const { Array retval (*this); @@ -309,17 +304,38 @@ return retval; } + //! @name First dimension + //! + //! Get the first dimension of the array (number of rows) + //@{ + octave_idx_type dim1 (void) const { return dimensions(0); } octave_idx_type rows (void) const { return dim1 (); } + //@} + + //! @name Second dimension + //! + //! Get the second dimension of the array (number of columns) + //@{ + octave_idx_type dim2 (void) const { return dimensions(1); } octave_idx_type cols (void) const { return dim2 (); } octave_idx_type columns (void) const { return dim2 (); } + //@} + + //! @name Third dimension + //! + //! Get the third dimension of the array (number of pages) + //@{ + octave_idx_type dim3 (void) const { return dimensions(2); } octave_idx_type pages (void) const { return dim3 (); } + //@} size_t byte_size (void) const { return static_cast (numel ()) * sizeof (T); } - // Return a const-reference so that dims ()(i) works efficiently. + //! Return a const-reference so that dims ()(i) works efficiently. const dim_vector& dims (void) const { return dimensions; } + //! Chop off leading singleton dimensions Array squeeze (void) const; void chop_trailing_singletons (void) GCC_ATTR_DEPRECATED @@ -434,13 +450,13 @@ // Fast extractors. All of these produce shallow copies. // Warning: none of these do check bounds, unless BOUNDS_CHECKING is on! - // Extract column: A(:,k+1). + //! Extract column: A(:,k+1). Array column (octave_idx_type k) const; - // Extract page: A(:,:,k+1). + //! Extract page: A(:,:,k+1). Array page (octave_idx_type k) const; - // Extract a slice from this array as a column vector: A(:)(lo+1:up). - // Must be 0 <= lo && up <= numel. May be up < lo. + //! Extract a slice from this array as a column vector: A(:)(lo+1:up). + //! Must be 0 <= lo && up <= numel. May be up < lo. Array linear_slice (octave_idx_type lo, octave_idx_type up) const; Array reshape (octave_idx_type nr, octave_idx_type nc) const @@ -472,18 +488,19 @@ int ndims (void) const { return dimensions.length (); } - // Indexing without resizing. - + //@{ + //! Indexing without resizing. Array index (const idx_vector& i) const; Array index (const idx_vector& i, const idx_vector& j) const; Array index (const Array& ia) const; + //@} virtual T resize_fill_value (void) const; - // Resizing (with fill). - + //@{ + //! Resizing (with fill). void resize1 (octave_idx_type n, const T& rfv); void resize1 (octave_idx_type n) { resize1 (n, resize_fill_value ()); } @@ -502,11 +519,15 @@ void resize (const dim_vector& dv, const T& rfv); void resize (const dim_vector& dv) { resize (dv, resize_fill_value ()); } + //@} - // Indexing with possible resizing and fill - // FIXME: this is really a corner case, that should better be + //@{ + //! Indexing with possible resizing and fill + + // FIXME -- this is really a corner case, that should better be // handled directly in liboctinterp. + Array index (const idx_vector& i, bool resize_ok, const T& rfv) const; Array index (const idx_vector& i, bool resize_ok) const { @@ -527,9 +548,11 @@ { return index (ia, resize_ok, resize_fill_value ()); } + //@} - // Indexed assignment (always with resize & fill). + //@{ + //! Indexed assignment (always with resize & fill). void assign (const idx_vector& i, const Array& rhs, const T& rfv); void assign (const idx_vector& i, const Array& rhs) { @@ -548,25 +571,28 @@ { assign (ia, rhs, resize_fill_value ()); } + //@} - // Deleting elements. + //@{ + //! Deleting elements. - // A(I) = [] (with a single subscript) + //! A(I) = [] (with a single subscript) void delete_elements (const idx_vector& i); - // A(:,...,I,...,:) = [] (>= 2 subscripts, one of them is non-colon) + //! A(:,...,I,...,:) = [] (>= 2 subscripts, one of them is non-colon) void delete_elements (int dim, const idx_vector& i); - // Dispatcher to the above two. + //! Dispatcher to the above two. void delete_elements (const Array& ia); + //@} - // Insert an array into another at a specified position. - // If size (a) is [d1 d2 ... dN] and idx is [i1 i2 ... iN], - // this method is equivalent to - // x(i1:i1+d1-1, i2:i2+d2-1, ... , iN:iN+dN-1) = a. + //! Insert an array into another at a specified position. If + //! size (a) is [d1 d2 ... dN] and idx is [i1 i2 ... iN], this + //! method is equivalent to x(i1:i1+d1-1, i2:i2+d2-1, ... , + //! iN:iN+dN-1) = a. Array& insert (const Array& a, const Array& idx); - // This is just a special case for idx = [r c 0 ...] + //! This is just a special case for idx = [r c 0 ...] Array& insert (const Array& a, octave_idx_type r, octave_idx_type c); void maybe_economize (void) @@ -582,54 +608,60 @@ void print_info (std::ostream& os, const std::string& prefix) const; - // Unsafe. This function exists to support the MEX interface. - // You should not use it anywhere else. + //! Give a pointer to the data in mex format. Unsafe. This function + //! exists to support the MEX interface. You should not use it + //! anywhere else. void *mex_get_data (void) const { return const_cast (data ()); } Array sort (int dim = 0, sortmode mode = ASCENDING) const; Array sort (Array &sidx, int dim = 0, sortmode mode = ASCENDING) const; - // Ordering is auto-detected or can be specified. + //! Ordering is auto-detected or can be specified. sortmode is_sorted (sortmode mode = UNSORTED) const; - // Sort by rows returns only indices. + //! Sort by rows returns only indices. Array sort_rows_idx (sortmode mode = ASCENDING) const; - // Ordering is auto-detected or can be specified. + //! Ordering is auto-detected or can be specified. sortmode is_sorted_rows (sortmode mode = UNSORTED) const; - // 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. + //! @brief 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; - // Ditto, but for an array of values, specializing on the case when values - // are sorted. NaNs get the value N. + //! Ditto, but for an array of values, specializing on the case when values + //! are sorted. NaNs get the value N. Array lookup (const Array& values, sortmode mode = UNSORTED) const; - // Count nonzero elements. + //! Count nonzero elements. octave_idx_type nnz (void) const; - // Find indices of (at most n) nonzero elements. If n is specified, backward - // specifies search from backward. - Array find (octave_idx_type n = -1, - bool backward = false) const; + //! Find indices of (at most n) nonzero elements. If n is specified, + //! backward specifies search from backward. + Array find (octave_idx_type n = -1, bool backward = false) const; - // Returns the n-th element in increasing order, using the same ordering as - // used for sort. n can either be a scalar index or a contiguous range. + //! Returns the n-th element in increasing order, using the same + //! ordering as used for sort. n can either be a scalar index or a + //! contiguous range. Array nth_element (const idx_vector& n, int dim = 0) const; + //! Get the kth super or subdiagonal. The zeroth diagonal is the + //! ordinary diagonal. Array diag (octave_idx_type k = 0) const; Array diag (octave_idx_type m, octave_idx_type n) const; - // Concatenation along a specified (0-based) dimension, equivalent to cat(). - // dim = -1 corresponds to dim = 0 and dim = -2 corresponds to dim = 1, - // but apply the looser matching rules of vertcat/horzcat. + //! Concatenation along a specified (0-based) dimension, equivalent + //! to cat(). dim = -1 corresponds to dim = 0 and dim = -2 + //! corresponds to dim = 1, but apply the looser matching rules of + //! vertcat/horzcat. static Array cat (int dim, octave_idx_type n, const Array *array_list); + //! Apply function fcn to each element of the Array. This function + //! is optimised with a manually unrolled loop. template Array map (F fcn) const @@ -660,7 +692,8 @@ return result; } - // Overloads for function references. + //@{ + //! Overloads for function references. template Array map (U (&fcn) (T)) const @@ -670,15 +703,17 @@ Array map (U (&fcn) (const T&)) const { return map (fcn); } + //@} - // Generic any/all test functionality with arbitrary predicate. + //! Generic any/all test functionality with arbitrary predicate. template bool test (F fcn) const { return any_all_test (fcn, data (), length ()); } - // Simpler calls. + //@{ + //! Simpler calls. template bool test_any (F fcn) const { return test (fcn); } @@ -686,8 +721,10 @@ template bool test_all (F fcn) const { return test (fcn); } + //@} - // Overloads for function references. + //@{ + //! Overloads for function references. bool test_any (bool (&fcn) (T)) const { return test (fcn); } @@ -699,16 +736,18 @@ bool test_all (bool (&fcn) (const T&)) const { return test (fcn); } + //@} template friend class Array; - // Returns true if this->dims () == dv, and if so, replaces this->dimensions - // by a shallow copy of dv. This is useful for maintaining several arrays with - // supposedly equal dimensions (e.g. structs in the interpreter). + //! Returns true if this->dims () == dv, and if so, replaces this->dimensions + //! by a shallow copy of dv. This is useful for maintaining several arrays with + //! supposedly equal dimensions (e.g. structs in the interpreter). bool optimize_dimensions (const dim_vector& dv); - // WARNING: Only call these functions from jit - + //@{ + //! WARNING: Only call these functions from jit + int *jit_ref_count (void) { return rep->count.get (); } T *jit_slice_data (void) const { return slice_data; } @@ -716,6 +755,7 @@ octave_idx_type *jit_dimensions (void) const { return dimensions.to_jit (); } void *jit_array_rep (void) const { return rep; } + //@} private: @@ -728,12 +768,11 @@ static void instantiation_guard (); }; -// This is a simple wrapper template that will subclass an Array type or any -// later type derived from it and override the default non-const operator() to -// not check for the array's uniqueness. It is, however, the user's -// responsibility to ensure the array is actually unaliased whenever elements -// are accessed. - +//! This is a simple wrapper template that will subclass an Array +//! type or any later type derived from it and override the default +//! non-const operator() to not check for the array's uniqueness. It +//! is, however, the user's responsibility to ensure the array is +//! actually unaliased whenever elements are accessed. template class NoAlias : public ArrayClass {