From d4ae39ddedfbe99e59f6cc774fa045ca29e7afc4 Mon Sep 17 00:00:00 2001 From: Charles Edward Pax Date: Sun, 30 Jul 2017 10:34:58 -0400 Subject: Doxygen comments in yank.c. --- src/yank.c | 145 +++++++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 117 insertions(+), 28 deletions(-) diff --git a/src/yank.c b/src/yank.c index ff46223..c3e243c 100644 --- a/src/yank.c +++ b/src/yank.c @@ -1,10 +1,53 @@ -/* - * Yanklist doesn't keep references to 'ent' elements, it creates new nodes. - * the yanklist is constantly cleaned out. - * Ex.: When removing 'ent' elements with `dc`, the original ones are removed - * and new elements are created in the yanklist. - * Important: each 'ent' element should keep a row and col. +/******************************************************************************* + * Copyright (c) 2013-2017, Andrés Martinelli . * + * 4. Neither the name of the Andrés Martinelli nor the * + * names of other contributors may be used to endorse or promote products * + * derived from this software without specific prior written permission. * + * * + * THIS SOFTWARE IS PROVIDED BY ANDRES MARTINELLI ''AS IS'' AND ANY * + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * + * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * + * DISCLAIMED. IN NO EVENT SHALL ANDRES MARTINELLI BE LIABLE FOR ANY * + * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;* + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * + *******************************************************************************/ + +/** + * \file yank.c + * \author Andrés Martinelli + * \date 2017-07-18 + * \brief TODO Write a tbrief file description. + * + * \details Yanklist doesn't keep references to 'ent' elements, it + * creates new nodes.Tthe yanklist is constantly cleaned out. Example: When + * removing 'ent' elements with `dc`, the original ones are removed + * and new elements are created in the yanklist. Important: each 'ent' + * element should keep a row and col. */ + #include "sc.h" #include "stdlib.h" #include "marks.h" @@ -25,16 +68,33 @@ int yank_arg; // number of rows and columns yanked. Used for com char type_of_yank; // yank type. c=col, r=row, a=range, e=cell, '\0'=no yanking static struct ent * yanklist; +/** + * \brief TODO Document init_yanklist() + * + * \return none + */ + void init_yanklist() { type_of_yank = '\0'; yanklist = NULL; } +/** + * \brief Return the yanklist + * + * \return yanklist + */ + struct ent * get_yanklist() { return yanklist; } -// Remove yank 'ent' elements and free corresponding memory +/** + * \brief Remove yank 'ent' elements and free corresponding memory + * + * \return none + */ + void free_yanklist () { if (yanklist == NULL) return; int c; @@ -62,7 +122,12 @@ void free_yanklist () { return; } -// Count and return number of entries in the yanklist +/** + * \brief Count and return number of entries in the yanklist + * + * \return number of yanklist entries + */ + int count_yank_ents() { int i = 0; @@ -74,7 +139,13 @@ int count_yank_ents() { return i; } -// Add 'ent' element to the yanklist +/** + * \brief Add 'ent' element to the yanklist + * + * \param[in] item 'ent' element to add to the yanklist + * \return none + */ + void add_ent_to_yanklist(struct ent * item) { // Create and initialize the 'ent' struct ent * i_ent = (struct ent *) malloc (sizeof(struct ent)); @@ -113,12 +184,21 @@ void add_ent_to_yanklist(struct ent * item) { return; } -/* - * yank a range of ents - * ARG: number of rows or columns yanked. Used in commands like `4yr` - * TYPE: yank type. c=col, r=row, a=range, e=cell, '\0'=no yanking, 's' sort - * This two args are used for pasting. +/** + * \brief Yank a range of ents + * + * \param[in] tlrow + * \param[in] tlcol + * \param[in] brrow + * \param[in] brcol + * \param[in] type yank type. c=col, r=row, a=range, e=cell. '\o'=no yanking, + * 's' sort. Used for pasting. + * \param[in] arg number of rows or columns yanked. Used in commands like + * '4yr'. Used for pasting. + * + * \return none */ + void yank_area(int tlrow, int tlcol, int brrow, int brcol, char type, int arg) { int r,c; free_yanklist(); @@ -137,21 +217,30 @@ void yank_area(int tlrow, int tlcol, int brrow, int brcol, char type, int arg) { return; } -/* - * paste yanked ents: - * this function is used for paste ents that were yanked with yr yc dr dc.. - * it is also used for sorting. - * if above == 1, paste is done above current row or to the right of current col. - * ents that were yanked using yy or yanked ents of a range, are always pasted in currow and curcol positions. - * diffr: diff between current rows and the yanked 'ent' - * diffc: diff between current cols and the yanked 'ent' - * When sorting, row and col values can vary from yank to paste time, so diffr - * should be zero. - * When implementing column sorting, diffc should be zero as well! - * type indicates if pasting format only, value only or the whole content - * yank type: c=col, r=row, a=range, e=cell, '\0'=no yanking - * returns -1 if locked cells are found. 0 otherwise. +/** + * \brief Paste yanked ents + * + * \details This function is used for pasting ents that were yanked + * with tr, yc, dr, or dc. It is also used for sorting. + * \details If above == 1, paste is done above current row or the + * right of the current column. Enst that were yanked using yy or yanked + * ents of a range, always pasted in currow and curcol positions. + * \details diffr: difference between current rows and the yanked 'ent' + * \details diffc: difference between current columns and the yanked 'ent' + * \details When sorting, rwo and col values can vary from yank to paste + * time, so diffr should be zero. + * \details When implementing column sorting, diffc should be zero as well! + * \details type indicates if pasting format only, valuue only for the + * whole content. + * \details yank type: c=col, r=row, a=range, e=cell, '\0'=no yanking. + * + * \param[in] above + * \param[in] type_paste + * + * \return -1 if locked cells are found + * \return 0 otherwise */ + int paste_yanked_ents(int above, int type_paste) { if (! count_yank_ents()) return 0; -- cgit v1.2.3