From 0942d9f6f6057e83fb542a008dfc80c6e1dcc98e Mon Sep 17 00:00:00 2001

From: Pranav Kant <pranavk@gnome.org>

Date: Thu, 24 Sep 2015 14:41:26 +0200

Subject: [PATCH 161/398] Move all introspection comments to header file

... wherever possible. There are few things we can't move to

header file, for example, the comments corresponding to GObject

properties, and signals.

Change-Id: If74d61b17ccee11f8a056f3a93040d2cff2dd98d

Reviewed-on: https://gerrit.libreoffice.org/18863

Reviewed-by: Miklos Vajna <vmiklos@collabora.co.uk>

Tested-by: Miklos Vajna <vmiklos@collabora.co.uk>

(cherry picked from commit 392437393d97a157e8291d20f1d6b6ac357ff0db)

---

 include/LibreOfficeKit/LibreOfficeKitGtk.h | 132 ++++++++++++++++++++++++++++-

 libreofficekit/source/gtk/lokdocview.cxx   |  87 +------------------

 2 files changed, 129 insertions(+), 90 deletions(-)

diff --git a/include/LibreOfficeKit/LibreOfficeKitGtk.h b/include/LibreOfficeKit/LibreOfficeKitGtk.h

index f17925b4c53a..81f42105d374 100644

--- a/include/LibreOfficeKit/LibreOfficeKitGtk.h

+++ b/include/LibreOfficeKit/LibreOfficeKitGtk.h

@@ -40,54 +40,178 @@ struct _LOKDocViewClass

 GType                          lok_doc_view_get_type               (void) G_GNUC_CONST;

+/**

+ * lok_doc_view_new:

+ * @pPath: LibreOffice install path.

+ * @cancellable: The cancellable object that you can use to cancel this

+ * operation.

+ * @error: The error that will be set if the object fails to initialize.

+ *

+ * Returns: (transfer none): The #LOKDocView widget instance.

+ */

 GtkWidget*                     lok_doc_view_new                    (const gchar* pPath,

                                                                     GCancellable *cancellable,

                                                                     GError **error);

+/**

+ * lok_doc_view_new_from_widget:

+ * @pDocView: The #LOKDocView instance

+ *

+ * Returns: (transfer none): The #LOKDocView widget instance.

+ */

 GtkWidget*                     lok_doc_view_new_from_widget        (LOKDocView* pDocView);

+/**

+ * lok_doc_view_open_document:

+ * @pDocView: The #LOKDocView instance

+ * @pPath: (transfer full): The path of the document that #LOKDocView widget should try to open

+ * @cancellable:

+ * @callback:

+ * @userdata:

+ *

+ * Returns: %TRUE if the document is loaded succesfully, %FALSE otherwise

+ */

 void                           lok_doc_view_open_document          (LOKDocView* pDocView,

                                                                     const gchar* pPath,

                                                                     GCancellable* cancellable,

                                                                     GAsyncReadyCallback callback,

                                                                     gpointer userdata);

+/**

+ * lok_doc_view_open_document_finish:

+ * @pDocView: The #LOKDocView instance

+ * @res:

+ * @error:

+ *

+ * Returns: %TRUE if the document is loaded succesfully, %FALSE otherwise

+ */

 gboolean                       lok_doc_view_open_document_finish   (LOKDocView* pDocView,

                                                                     GAsyncResult* res,

                                                                     GError** error);

-/// Gets the document the viewer displays.

+/**

+ * lok_doc_view_get_document:

+ * @pDocView: The #LOKDocView instance

+ *

+ * Gets the document the viewer displays.

+ *

+ * Returns: The #LibreOfficeKitDocument instance the widget is currently showing

+ */

 LibreOfficeKitDocument*        lok_doc_view_get_document           (LOKDocView* pDocView);

+/**

+ * lok_doc_view_set_zoom:

+ * @pDocView: The #LOKDocView instance

+ * @fZoom: The new zoom level that pDocView must set it into.

+ *

+ * Sets the new zoom level for the widget.

+ */

 void                           lok_doc_view_set_zoom               (LOKDocView* pDocView,

                                                                     float fZoom);

+

+/**

+ * lok_doc_view_get_zoom:

+ * @pDocView: The #LOKDocView instance

+ *

+ * Returns: The current zoom factor value in float for pDocView

+ */

 float                          lok_doc_view_get_zoom               (LOKDocView* pDocView);

+/**

+ * lok_doc_view_get_parts:

+ * @pDocView: The #LOKDocView instance

+ */

 int                            lok_doc_view_get_parts              (LOKDocView* pDocView);

+

+/**

+ * lok_doc_view_get_part:

+ * @pDocView: The #LOKDocView instance

+ */

 int                            lok_doc_view_get_part               (LOKDocView* pDocView);

+

+/**

+ * lok_doc_view_set_part:

+ * @pDocView: The #LOKDocView instance

+ * @nPart:

+ */

 void                           lok_doc_view_set_part               (LOKDocView* pDocView,

                                                                     int nPart);

+

+/**

+ * lok_doc_view_get_part_name:

+ * @pDocView: The #LOKDocView instance

+ * @nPart:

+ */

 char*                          lok_doc_view_get_part_name          (LOKDocView* pDocView,

                                                                     int nPart);

+

+/**

+ * lok_doc_view_set_partmode:

+ * @pDocView: The #LOKDocView instance

+ * @nPartMode:

+ */

 void                           lok_doc_view_set_partmode           (LOKDocView* pDocView,

                                                                     int nPartMode);

+/**

+ * lok_doc_view_reset_view:

+ * @pDocView: The #LOKDocView instance

+ */

 void                           lok_doc_view_reset_view             (LOKDocView* pDocView);

-/// Sets if the viewer is actually an editor or not.

+/**

+ * lok_doc_view_set_edit:

+ * @pDocView: The #LOKDocView instance

+ * @bEdit: %TRUE if the pDocView should go in edit mode, %FALSE otherwise

+ *

+ * Sets if the viewer is actually an editor or not.

+ */

 void                           lok_doc_view_set_edit               (LOKDocView* pDocView,

                                                                     gboolean bEdit);

-/// Gets if the viewer is actually an editor or not.

+

+/**

+ * lok_doc_view_get_edit:

+ * @pDocView: The #LOKDocView instance

+ *

+ * Gets if the viewer is actually an editor or not.

+ *

+ * Returns: %TRUE if the given pDocView is in edit mode.

+ */

 gboolean                       lok_doc_view_get_edit               (LOKDocView* pDocView);

-/// Posts the .uno: command to the LibreOfficeKit.

+/**

+ * lok_doc_view_post_command:

+ * @pDocView: the #LOKDocView instance

+ * @pCommand: the command to issue to LO core

+ * @pArguments: the arguments to the given command

+ *

+ * Posts the .uno: command to the LibreOfficeKit.

+ */

 void                           lok_doc_view_post_command           (LOKDocView* pDocView,

                                                                     const gchar* pCommand,

                                                                     const gchar* pArguments);

+/**

+ * lok_doc_view_pixel_to_twip:

+ * @pDocView: The #LOKDocView instance

+ * @fInput: The value in pixels to convert to twips

+ *

+ * Converts the value in pixels to twips according to zoom level.

+ *

+ * Returns: The corresponding value in twips

+ */

 float                          lok_doc_view_pixel_to_twip          (LOKDocView* pDocView,

                                                                     float fInput);

+/**

+ * lok_doc_view_twip_to_pixel:

+ * @pDocView: The #LOKDocView instance

+ * @fInput: The value in twips to convert to pixels

+ *

+ * Converts the value in twips to pixels according to zoom level.

+ *

+ * Returns: The corresponding value in pixels

+ */

 float                          lok_doc_view_twip_to_pixel          (LOKDocView* pDocView,

                                                                     float fInput);

diff --git a/libreofficekit/source/gtk/lokdocview.cxx b/libreofficekit/source/gtk/lokdocview.cxx

index 60304b4ff59c..7c52ce2e2efb 100644

--- a/libreofficekit/source/gtk/lokdocview.cxx

+++ b/libreofficekit/source/gtk/lokdocview.cxx

@@ -1843,15 +1843,6 @@ static void lok_doc_view_class_init (LOKDocViewClass* pClass)

                      G_TYPE_INT, G_TYPE_INT);

 }

-/**

- * lok_doc_view_new:

- * @pPath: LibreOffice install path.

- * @cancellable: The cancellable object that you can use to cancel this

- * operation.

- * @error: The error that will be set if the object fails to initialize.

- *

- * Returns: (transfer none): The #LOKDocView widget instance.

- */

 SAL_DLLPUBLIC_EXPORT GtkWidget*

 lok_doc_view_new (const gchar* pPath, GCancellable *cancellable, GError **error)

 {

@@ -1873,14 +1864,6 @@ SAL_DLLPUBLIC_EXPORT GtkWidget* lok_doc_view_new_from_widget(LOKDocView* pOldLOK

     return pNewDocView;

 }

-/**

- * lok_doc_view_open_document_finish:

- * @pDocView: The #LOKDocView instance

- * @res:

- * @error:

- *

- * Returns: %TRUE if the document is loaded succesfully, %FALSE otherwise

- */

 SAL_DLLPUBLIC_EXPORT gboolean

 lok_doc_view_open_document_finish (LOKDocView* pDocView, GAsyncResult* res, GError** error)

 {

@@ -1894,17 +1877,6 @@ lok_doc_view_open_document_finish (LOKDocView* pDocView, GAsyncResult* res, GErr

     return g_task_propagate_boolean(task, error);

 }

-

-/**

- * lok_doc_view_open_document:

- * @pDocView: The #LOKDocView instance

- * @pPath: (transfer full): The path of the document that #LOKDocView widget should try to open

- * @cancellable:

- * @callback:

- * @userdata:

- *

- * Returns: %TRUE if the document is loaded succesfully, %FALSE otherwise

- */

 SAL_DLLPUBLIC_EXPORT void

 lok_doc_view_open_document (LOKDocView* pDocView,

                             const gchar* pPath,

@@ -1925,12 +1897,6 @@ lok_doc_view_open_document (LOKDocView* pDocView,

     g_object_unref(task);

 }

-/**

- * lok_doc_view_get_document:

- * @pDocView: The #LOKDocView instance

- *

- * Returns: The #LibreOfficeKitDocument instance the widget is currently showing

- */

 SAL_DLLPUBLIC_EXPORT LibreOfficeKitDocument*

 lok_doc_view_get_document (LOKDocView* pDocView)

 {

@@ -1938,13 +1904,6 @@ lok_doc_view_get_document (LOKDocView* pDocView)

     return priv->m_pDocument;

 }

-/**

- * lok_doc_view_set_zoom:

- * @pDocView: The #LOKDocView instance

- * @fZoom: The new zoom level that pDocView must set it into.

- *

- * Sets the new zoom level for the widget.

- */

 SAL_DLLPUBLIC_EXPORT void

 lok_doc_view_set_zoom (LOKDocView* pDocView, float fZoom)

 {

@@ -1963,12 +1922,6 @@ lok_doc_view_set_zoom (LOKDocView* pDocView, float fZoom)

                                 nDocumentHeightPixels);

 }

-/**

- * lok_doc_view_get_zoom:

- * @pDocView: The #LOKDocView instance

- *

- * Returns: The current zoom factor value in float for pDocView

- */

 SAL_DLLPUBLIC_EXPORT float

 lok_doc_view_get_zoom (LOKDocView* pDocView)

 {

@@ -2036,13 +1989,6 @@ lok_doc_view_reset_view(LOKDocView* pDocView)

     gtk_widget_queue_draw(GTK_WIDGET(pDocView));

 }

-/**

- * lok_doc_view_set_edit:

- * @pDocView: The #LOKDocView instance

- * @bEdit: %TRUE if the pDocView should go in edit mode, %FALSE otherwise

- *

- * Sets the edit-mode for pDocView

- */

 SAL_DLLPUBLIC_EXPORT void

 lok_doc_view_set_edit(LOKDocView* pDocView,

                       gboolean bEdit)

@@ -2057,12 +2003,6 @@ lok_doc_view_set_edit(LOKDocView* pDocView,

     g_object_unref(task);

 }

-/**

- * lok_doc_view_get_edit:

- * @pDocView: The #LOKDocView instance

- *

- * Returns: %TRUE if the given pDocView is in edit mode.

- */

 SAL_DLLPUBLIC_EXPORT gboolean

 lok_doc_view_get_edit (LOKDocView* pDocView)

 {

@@ -2070,14 +2010,7 @@ lok_doc_view_get_edit (LOKDocView* pDocView)

     return priv->m_bEdit;

 }

-/**

- * lok_doc_view_post_command:

- * @pDocView: the #LOKDocView instance

- * @pCommand: the command to issue to LO core

- * @pArguments: the arguments to the given command

- *

- * This methods forwards your command to LO core.

-*/

+

 SAL_DLLPUBLIC_EXPORT void

 lok_doc_view_post_command (LOKDocView* pDocView,

                            const gchar* pCommand,

@@ -2094,15 +2027,6 @@ lok_doc_view_post_command (LOKDocView* pDocView,

     g_object_unref(task);

 }

-/**

- * lok_doc_view_pixel_to_twip:

- * @pDocView: The #LOKDocView instance

- * @fInput: The value in pixels to convert to twips

- *

- * Converts the value in pixels to twips according to zoom level.

- *

- * Returns: The corresponding value in twips

- */

 SAL_DLLPUBLIC_EXPORT float

 lok_doc_view_pixel_to_twip (LOKDocView* pDocView, float fInput)

 {

@@ -2110,15 +2034,6 @@ lok_doc_view_pixel_to_twip (LOKDocView* pDocView, float fInput)

     return pixelToTwip(fInput, priv->m_fZoom);

 }

-/**

- * lok_doc_view_twip_to_pixel:

- * @pDocView: The #LOKDocView instance

- * @fInput: The value in twips to convert to pixels

- *

- * Converts the value in twips to pixels according to zoom level.

- *

- * Returns: The corresponding value in pixels

- */

 SAL_DLLPUBLIC_EXPORT float

 lok_doc_view_twip_to_pixel (LOKDocView* pDocView, float fInput)

 {

-- 

2.12.0