Improved doxygen documentation. Could people please have a look at Lars'

autogenerated files tomorrow (Thursday) and throw their comments my way.
http://www.lyx.org/sourcedoc/classDialog.html
http://www.lyx.org/sourcedoc/classKernel.html


git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@7292 a592a061-630c-0410-9148-cb99ea01b6c8

src/frontends/controllers/ChangeLog

@@ -1,3 +1,10 @@
+2003-07-16  Angus Leeming  <leeming@lyx.org>
+
+	Dialog.[Ch]: move a few methods out of line.
+
+	Dialog.h:
+	Kernel.h: improve doxygen documentation.
+
 2003-07-01  Lars Gullik Bjønnes  <larsbj@gullik.net>
 
 	* introduce namespace lyx::support

src/frontends/controllers/Dialog.C

@@ -149,6 +149,11 @@ ButtonController & Dialog::bc() const
 }
 
 
+Dialog::Controller::Controller(Dialog & parent)
+	: parent_(parent)
+{}
+
+
 Dialog::Controller & Dialog::controller() const
 {
 	Assert(controller_ptr_.get());
@@ -156,6 +161,11 @@ Dialog::Controller & Dialog::controller() const
 }
 
 
+Dialog::View::View(Dialog & parent, string title) :
+	p_(parent), title_(title)
+{}
+
+
 Dialog::View & Dialog::view() const
 {
 	Assert(view_ptr_.get());

src/frontends/controllers/Dialog.h

@@ -28,37 +28,36 @@ class ButtonController;
  */
 class Dialog : boost::noncopyable {
 public:
-	/** \param name the identifier given to the dialog by its parent
+	/// \param lv is the access point for the dialog to the LyX kernel.
-	 *  container.
+	/// \param name is the identifier given to the dialog by its parent
-	 */
+	/// container.
-	Dialog(LyXView &, string const & name);
+	Dialog(LyXView & lv, string const & name);
 	~Dialog();
 
-	/** the Dialog's name is the means by which a dialog identifies
+	/** The Dialog's name is the means by which a dialog identifies
 	 *  itself to the kernel.
 	 */
 	string const & name() const { return name_; }
 
-	//@{
+	/** \name Buttons
-	/** These methods are publicly accessible because they are invoked
+	 *  These methods are publicly accessible because they are invoked
 	 *  by the View when the user presses... guess what ;-)
 	 */
+	//@{
 	void ApplyButton();
 	void OKButton();
 	void CancelButton();
 	void RestoreButton();
 	//@}
 
+	/** \name Container Access
+	 *  These methods are publicly accessible because they are invoked
+	 *  by the parent container acting on commands from the LyX kernel.
+	 */
 	//@{
-	/** These methods are publicly accessible because they are invoked
+	/// \param data is a string encoding of the data to be displayed.
-	 *  by the parent container acting on commands from the kernel.
+	/// It is passed to the Controller to be translated into a useable form.
-	 */
-	/** \param data The dialog is passed a string encoding the data
-	 *  that it is to display. This string is passed to the Controller
-	 *  which translates it into a useable form.
-	 */
 	void show(string const & data);
-	/// \param data \see show().
 	void update(string const & data);
 
 	void hide();
@@ -81,32 +80,35 @@ public:
 	 */
 	Kernel & kernel() { return kernel_; }
 
-	//@{
 	/** Different dialogs will have different Controllers and Views.
-	 * deriving from these base classes.
+	 *  deriving from these base classes.
 	 */
+	//@{
 	class Controller;
 	class View;
 	//@}
 
-	//@{
+	/** \name Dialog Specialization
-	/** Methods to set the Controller and View and so specialise
+	 *  Methods to set the Controller and View and so specialise
 	 *  to a particular dialog.
-	 *  \param ptr is stored here.
 	 */
+	//@{
+	/// \param ptr is stored and destroyed by \c Dialog.
 	void setController(Controller * ptr);
+	/// \param ptr is stored and destroyed by \c Dialog.
 	void setView(View * ptr);
 	//@}
 
+	/** \name Dialog Components
+	 *  Methods to access the various components making up a dialog.
+	 */
 	//@{
-	/// Get methods for the various components making up a dialog.
 	Controller & controller() const;
 	ButtonController & bc() const;
 	View & view() const;
 	//@}
 
 private:
-	/// Invoked by both OKButton() and ApplyButton().
 	void apply();
 
 	bool is_closing_;
@@ -123,30 +125,32 @@ private:
  */
 class Dialog::Controller : boost::noncopyable {
 public:
-	Controller(Dialog & parent) : parent_(parent) {}
+	/// \param parent Dialog owning this Controller.
+	Controller(Dialog & parent);
 	virtual ~Controller() {}
 
-	//@{
+	/** \name Generic Controller
-	/** These few methods are all that a generic dialog needs of a
+	 *  These few methods are all that a generic dialog needs of a
 	 *  controller.
 	 */
-	/** \param data The controller is passed a string encoding of the
+	//@{
-	 *  parameters that the dialog is to display.
+	/** Enable the controller to initialise its data structures.
+	 *  \param data is a string encoding of the parameters to be displayed.
 	 *  \return true if the translation was successful.
 	 */
 	virtual bool initialiseParams(string const & data) = 0;
-	/** Invoked by Dialog::hide, allowing the controller to
+
-	 *  clean up its data structures.
+	/// Enable the controller to clean up its data structures.
-	 */
 	virtual void clearParams() = 0;
-	/** Invoked by Dialog::apply, enabling the Controller to
+
-	 *  dispatch its data back to the LyX kernel.
+	/// Enable the Controller to dispatch its data back to the LyX kernel.
-	 */
 	virtual void dispatchParams() = 0;
+
 	/** \return true if the dialog should be shown only when
-	 *  a buffer is open
+	 *  a buffer is open.
 	 */
 	virtual bool isBufferDependent() const = 0;
+
 	/** \return true if the kernel should disconnect the dialog from
 	 *  a particular inset after the data has been applied to it.
 	 *  Clearly this makes sense only for dialogs modifying the contents
@@ -158,10 +162,10 @@ public:
 	//@}
 
 protected:
-	//@{
+	/** \name Controller Access
-	/** Enable the derived classes to access the other parts of the
+	 *  Enable the derived classes to access the other parts of the whole.
-	 * whole.
 	 */
+	//@{
 	Dialog & dialog() { return parent_; }
 	Dialog const & dialog() const { return parent_; }
 
@@ -179,35 +183,35 @@ private:
  */
 class Dialog::View : boost::noncopyable {
 public:
-	View(Dialog & parent, string title) : p_(parent), title_(title) {}
+	/** \param parent Dialog owning this Controller.
+	 *  \param title  is the dialog title displayed by the WM.
+	 */
+	View(Dialog & parent, string title);
 	virtual ~View() {}
 
-	//@{
+	/** \name Generic View
-	/** These few methods are all that a generic dialog needs of a
+	 *  These few methods are all that a generic dialog needs of a
 	 *  view.
 	 */
+	//@{
 	/** A request to modify the data structures stored by the
 	 *  accompanying Controller in preparation for their dispatch to
 	 *  the LyX kernel.
-	 *  Invoked by Dialog::apply.
 	 */
 	virtual void apply() = 0;
-	/** Hide the dialog from sight
+
-	 *  Invoked by Dialog::hide.
+	/// Hide the dialog from sight
-	 */
 	virtual void hide() = 0;
-	/** Redraw the dialog (e.g. if the colors have been remapped).
+
-	 *  Invoked by Dialog::redraw.
+	/// Redraw the dialog (e.g. if the colors have been remapped).
-	 */
 	virtual void redraw() {}
-	/** Create the dialog if necessary, update it and display it.
+
-	 *  Invoked by Dialog::show.
+	/// Create the dialog if necessary, update it and display it.
-	 */
 	virtual void show() = 0;
-	/** Update the display of the dialog whilst it is still visible.
+
-	 *  Invoked by Dialog::update.
+	/// Update the display of the dialog whilst it is still visible.
-	 */
 	virtual void update() = 0;
+
 	/// \return true if the dialog is visible.
 	virtual bool isVisible() const = 0;
 	//@}
@@ -215,21 +219,22 @@ public:
 	/** Defaults to nothing. Can be used by the Controller, however, to
 	 *  indicate to the View that something has changed and that the
 	 *  dialog therefore needs updating.
+	 *  \param id identifies what should be updated.
 	 */
-	virtual void partialUpdate(int) {}
+	virtual void partialUpdate(int id) {}
-
-	//@{
-	/** Enable the derived classes to access the other parts of the
-	 * whole.
-	 */
-	Dialog & dialog() { return p_; }
-	Dialog const & dialog() const { return p_; }
 
 	/// sets the title of the dialog (window caption)
 	void setTitle(string const &);
 	/// gets the title of the dialog (window caption)
 	string const & getTitle() const;
 
+	/** \name View Access
+	 *  Enable the derived classes to access the other parts of the whole.
+	 */
+	//@{
+	Dialog & dialog() { return p_; }
+	Dialog const & dialog() const { return p_; }
+
 protected:
 	Kernel & kernel() { return p_.kernel(); }
 	Kernel const & kernel() const { return p_.kernel(); }
@@ -242,9 +247,7 @@ protected:
 	//@}
 
 private:
-	///
 	Dialog & p_;
-	///
 	string title_;
 };
 

src/frontends/controllers/Kernel.h

@@ -26,27 +26,26 @@ class LyXView;
  * (Ie, it provides an interface to the Model part of the Model-Controller-
  *  View split.
  *  In an ideal world, it will shrink as more info is passed to the
- *  Dialog::show() and update() methods.
+ *  Dialog::show() and Dialog::update() methods.
  */
 class Kernel {
 public:
 	/// \param lv is the access point for the dialog to the LyX kernel.
 	Kernel(LyXView & lv);
 
-	/** This method is the primary prupose of the class. It provides
+	/** This method is the primary puypose of the class. It provides
-	    the "gateway" by which the dialog can send a request (of a
+	 *  the "gateway" by which the dialog can send a request (of a
-	    change in the data, for more information) to the kernel,
+	 *  change in the data, for more information) to the kernel.
-	    encoded as \param fr.
+	 *  \param fr is the encoding of the request.
-	    \param verbose Set to true if the completed action should
+	 *  \param verbose is set to true if the completed action should
-	    be displayed in the minibuffer.
+	 *  be displayed in the minibuffer.
 	 */
 	void dispatch(FuncRequest const & fr, bool verbose = false) const;
 
 	/** The dialog has received a request from the user
-	    (who pressed the "Restore" buuton) to update  contents.
+	 *  (who pressed the "Restore" buuton) to update contents.
-	    It must, therefore, ask the kernel to provide this information.
+	 *  It must, therefore, ask the kernel to provide this information.
-	    \param name is used as an identifier by the kernel
+	 *  \param name is used to identify the dialog to the kernel.
-	    when the information is posted.
 	 */
 	void updateDialog(string const & name) const;
 
@@ -54,17 +53,19 @@ public:
 	 *  stored by the dialog are not applied to the inset currently
 	 *  connected to the dialog. Instead, they will be used to generate
 	 *  a new inset at the cursor position.
+	 *  \param name is used to identify the dialog to the kernel.
 	 */
 	void disconnect(string const & name) const;
 
+	/** \name Kernel Wrappers
+	 *  Simple wrapper functions to Buffer methods.
+	 */
 	//@{
-	/// Simple wrapper functions to Buffer methods.
 	bool isBufferAvailable() const;
 	bool isBufferReadonly() const;
 	//@}
 
-	//@{
+	/** \enum DocTypes used to flag the different kinds of buffer
-	/** \enum DocTypes is used to flag the different kinds of buffer
 	 *  without making the kernel header files available to the
 	 *  dialog's Controller or View.
 	 */
@@ -76,13 +77,13 @@ public:
 	};
 	/// The type of the current buffer.
 	DocTypes docType() const;
-	//@}
 
 
-	//@{
+	/** \name Kernel Nasties
-	/** Unpleasantly public internals of the LyX kernel.
+	 *  Unpleasantly public internals of the LyX kernel.
 	 *  We should aim to reduce/remove these from the interface.
 	 */
+	//@{
 	LyXView & lyxview() { return lyxview_; }
 	LyXView const & lyxview() const { return lyxview_; }