From f73fb4a2f4e164b516e51a8c3bc7d1d8548d0777 Mon Sep 17 00:00:00 2001
From: Georg Baum <Georg.Baum@post.rwth-aachen.de>
Date: Thu, 4 Jan 2007 16:50:03 +0000
Subject: [PATCH] Add some documentation. Yes I know that some functions are
 misnamed :-(

git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@16509 a592a061-630c-0410-9148-cb99ea01b6c8
---
 src/CutAndPaste.C |  9 ++++-----
 src/CutAndPaste.h | 44 +++++++++++++++++++++++++++++++-------------
 2 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/src/CutAndPaste.C b/src/CutAndPaste.C
index c899efac69..a975b66378 100644
--- a/src/CutAndPaste.C
+++ b/src/CutAndPaste.C
@@ -641,7 +641,6 @@ void pasteSelection(LCursor & cur, ErrorList & errorList, size_t sel_index)
 }
 
 
-// simple replacing. The font of the first selected character is used
 void replaceSelectionWithString(LCursor & cur, docstring const & str, bool backwards)
 {
 	recordUndo(cur);
@@ -680,7 +679,7 @@ void replaceSelection(LCursor & cur)
 
 void eraseSelection(LCursor & cur)
 {
-	//lyxerr << "LCursor::eraseSelection begin: " << cur << endl;
+	//lyxerr << "cap::eraseSelection begin: " << cur << endl;
 	CursorSlice const & i1 = cur.selBegin();
 	CursorSlice const & i2 = cur.selEnd();
 	if (i1.inset().asInsetMath()) {
@@ -707,13 +706,13 @@ void eraseSelection(LCursor & cur)
 	} else {
 		lyxerr << "can't erase this selection 1" << endl;
 	}
-	//lyxerr << "LCursor::eraseSelection end: " << cur << endl;
+	//lyxerr << "cap::eraseSelection end: " << cur << endl;
 }
 
 
 void selDel(LCursor & cur)
 {
-	//lyxerr << "LCursor::selDel" << endl;
+	//lyxerr << "cap::selDel" << endl;
 	if (cur.selection())
 		eraseSelection(cur);
 }
@@ -721,7 +720,7 @@ void selDel(LCursor & cur)
 
 void selClearOrDel(LCursor & cur)
 {
-	//lyxerr << "LCursor::selClearOrDel" << endl;
+	//lyxerr << "cap::selClearOrDel" << endl;
 	if (lyxrc.auto_region_delete)
 		selDel(cur);
 	else
diff --git a/src/CutAndPaste.h b/src/CutAndPaste.h
index 7702de319e..6d9aa935f3 100644
--- a/src/CutAndPaste.h
+++ b/src/CutAndPaste.h
@@ -30,27 +30,40 @@ class LCursor;
 
 namespace cap {
 
-///
+/// Get all elements of the cut buffer in plain text format.
 std::vector<docstring> const availableSelections(Buffer const & buffer);
-///
+/// Get the number of available elements in the cut buffer.
 size_type numberOfSelections();
-///
+/// Get the sel_index-th element of the cut buffer in plain text format.
 docstring getSelection(Buffer const & buffer, size_t sel_index);
 
-/* Replace using the font of the first selected character and select
+/**
+ * Replace using the font of the first selected character and select
  * the new string. When \c backwards == false, set anchor before
  * cursor; otherwise set cursor before anchor.
+ * Does handle undo.
  */
 void replaceSelectionWithString(LCursor & cur, docstring const & str,
 				bool backwards);
-/// replace selection helper
+/// If a selection exists, cut it and push it to the cut buffer.
+/// Does handle undo.
 void replaceSelection(LCursor & cur);
 
-///
+/**
+ * Cut the current selection and possibly push it to the cut buffer and
+ * system clipboard.
+ * Does handle undo.
+ * \param doclear If this is true: Delete leading spaces in paragraphs before
+ *                they get merged.
+ * \param realcut If this is true: Push the selection to the cut buffer and
+ *                system clipboard. Set this to false for internal cuts that
+ *                do not directly originate from the user.
+ */
 void cutSelection(LCursor & cur, bool doclear = true, bool realcut = true);
-///
+/// Push the current selection to the cut buffer and the system clipboard.
 void copySelection(LCursor & cur);
-///
+/// Paste the sel_index-th element of the cut buffer.
+/// Does handle undo. Does only work in text, not mathed.
 void pasteSelection(LCursor & cur, ErrorList &, size_t sel_index = 0);
 
 /// Paste the paragraph list \p parlist at the position given by \p cur.
@@ -66,16 +79,21 @@ void pasteParagraphList(LCursor & cur, ParagraphList const & parlist,
 void switchBetweenClasses(textclass_type c1, textclass_type c2,
                           InsetText & in, ErrorList &);
 
-///
+/// Get the current selection as a string. Does not change the selection.
+/// Does only work if the whole selection is in mathed.
 docstring grabSelection(LCursor const & cur);
-///
+/// Erase the current selection.
+/// Does not handle undo. Does only work if the whole selection is in mathed.
 void eraseSelection(LCursor & cur);
-///
+/// Erase the selection and return it as a string.
+/// Does not handle undo. Does only work if the whole selection is in mathed.
 docstring grabAndEraseSelection(LCursor & cur);
 // other selection methods
-///
+/// Erase the selection if one exists.
+/// Does not handle undo. Does only work if the whole selection is in mathed.
 void selDel(LCursor & cur);
-/// clears or deletes selection depending on lyxrc setting
+/// Clear or delete the selection if one exists, depending on lyxrc setting.
+/// Does not handle undo. Does only work if the whole selection is in mathed.
 void selClearOrDel(LCursor & cur);
 
 /** Tabular has its own paste stack for multiple cells
-- 
2.39.5