From b1924a9bcad053c267546fcc3005961ab98d4761 Mon Sep 17 00:00:00 2001 From: Angus Leeming Date: Wed, 16 Jul 2003 20:10:59 +0000 Subject: [PATCH] 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 | 7 ++ src/frontends/controllers/Dialog.C | 10 +++ src/frontends/controllers/Dialog.h | 129 ++++++++++++++-------------- src/frontends/controllers/Kernel.h | 35 ++++---- 4 files changed, 101 insertions(+), 80 deletions(-) diff --git a/src/frontends/controllers/ChangeLog b/src/frontends/controllers/ChangeLog index ccdcc247ab..0afbf127f7 100644 --- a/src/frontends/controllers/ChangeLog +++ b/src/frontends/controllers/ChangeLog @@ -1,3 +1,10 @@ +2003-07-16 Angus Leeming + + Dialog.[Ch]: move a few methods out of line. + + Dialog.h: + Kernel.h: improve doxygen documentation. + 2003-07-01 Lars Gullik Bjønnes * introduce namespace lyx::support diff --git a/src/frontends/controllers/Dialog.C b/src/frontends/controllers/Dialog.C index 95643a0b3f..3530ca4a48 100644 --- a/src/frontends/controllers/Dialog.C +++ b/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()); diff --git a/src/frontends/controllers/Dialog.h b/src/frontends/controllers/Dialog.h index dd23f45ed4..e3aef83733 100644 --- a/src/frontends/controllers/Dialog.h +++ b/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 - * container. - */ - Dialog(LyXView &, string const & name); + /// \param lv is the access point for the dialog to the LyX kernel. + /// \param name is the identifier given to the dialog by its parent + /// container. + 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_; } - //@{ - /** These methods are publicly accessible because they are invoked + /** \name Buttons + * 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 - * by the parent container acting on commands from the kernel. - */ - /** \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. - */ + /// \param data is a string encoding of the data to be displayed. + /// It is passed to the Controller to be translated 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; //@} - //@{ - /** Methods to set the Controller and View and so specialise + /** \name Dialog Specialization + * 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() {} - //@{ - /** These few methods are all that a generic dialog needs of a + /** \name Generic Controller + * 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: - //@{ - /** Enable the derived classes to access the other parts of the - * whole. + /** \name Controller Access + * Enable the derived classes to access the other parts of the 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() {} - //@{ - /** These few methods are all that a generic dialog needs of a + /** \name Generic View + * 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) {} - - //@{ - /** Enable the derived classes to access the other parts of the - * whole. - */ - Dialog & dialog() { return p_; } - Dialog const & dialog() const { return p_; } + virtual void partialUpdate(int id) {} /// 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_; }; diff --git a/src/frontends/controllers/Kernel.h b/src/frontends/controllers/Kernel.h index 87d61ddee7..2312a2415a 100644 --- a/src/frontends/controllers/Kernel.h +++ b/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 - the "gateway" by which the dialog can send a request (of a - change in the data, for more information) to the kernel, - encoded as \param fr. - \param verbose Set to true if the completed action should - be displayed in the minibuffer. + /** This method is the primary puypose of the class. It provides + * the "gateway" by which the dialog can send a request (of a + * change in the data, for more information) to the kernel. + * \param fr is the encoding of the request. + * \param verbose is set to true if the completed action should + * 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. - It must, therefore, ask the kernel to provide this information. - \param name is used as an identifier by the kernel - when the information is posted. + * (who pressed the "Restore" buuton) to update contents. + * It must, therefore, ask the kernel to provide this information. + * \param name is used to identify the dialog to the kernel. */ 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 is used to flag the different kinds of buffer + /** \enum DocTypes 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; - //@} - //@{ - /** Unpleasantly public internals of the LyX kernel. + /** \name Kernel Nasties + * 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_; }