master d5bb053: Fix documentation and coding style in recent xwidget commits

[Eli Zaretskii]

branch: master
commit d5bb053809bfe2f2605ada15a7ccd25d772b0102
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Fix documentation and coding style in recent xwidget commits
    
    * src/xwidget.c (Fmake_xwidget, find_widget)
    (xwidget_motion_or_crossing, xwidget_button_1, xwidget_button):
    Fix style in comments.
    (Fxwidget_perform_lispy_event): Doc fix.
    * src/xwidget.c (set_widget_if_text_view, kill_frame_xwidget_views):
    * src/keyboard.c (make_lispy_event): Fix style of braces.
    
    * lisp/xwidget.el (xwidget-webkit-isearch-mode): Fix keys in doc
    string.
    
    * doc/lispref/commands.texi (Xwidget Events): Fix markup and
    wording.
    * doc/lispref/display.texi (Xwidgets): Fix wording and markup.
    * doc/emacs/misc.texi (Embedded WebKit Widgets): Fix wording.
    
    * etc/NEWS: Fix wording and punctuation.
---
 doc/emacs/misc.texi       |   7 ++-
 doc/lispref/commands.texi |  89 ++++++++++++++++++---------------
 doc/lispref/display.texi  |  24 ++++-----
 etc/NEWS                  |  34 +++++++------
 lisp/xwidget.el           |  15 +++---
 src/keyboard.c            |  16 ++----
 src/xwidget.c             | 125 ++++++++++++++++++++++------------------------
 7 files changed, 153 insertions(+), 157 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 1207ab5..4b3c2ea 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2965,19 +2965,18 @@ You can also enable @code{xwidget-webkit-edit-mode} by 
typing @kbd{e}
 inside the xwidget webkit buffer.
 
 @findex xwidget-webkit-isearch-mode
-@cindex xwidget-webkit-isearch-mode
 @cindex searching in webkit buffers
   @code{xwidget-webkit-isearch-mode} is a minor mode that behaves
 similarly to incremental search (@pxref{Incremental Search}), but
 operates on the contents of a WebKit widget instead of the current
 buffer.  It is bound to @kbd{C-s} and @kbd{C-r} inside xwidget-webkit
-buffers.  When it is enabled through @kbd{C-r}, the initial search
-will be performed in reverse direction.
+buffers.  When it is invoked by @kbd{C-r}, the initial search will be
+performed in reverse direction.
 
 Typing any self-inserting character will cause the character to be
 inserted into the current search query.  Typing @kbd{C-s} will cause
 the WebKit widget to display the next search result, while typing
-@kbd{C-r} will cause it to display the last.
+@kbd{C-r} will cause it to display the previous one.
 
 To leave incremental search, you can type @kbd{C-g}.
 
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 832b570..6ed46fa 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1883,53 +1883,62 @@ contain various data describing the nature of the 
change.
 @cindex @code{xwidget-event} event
 @item (xwidget-event @var{kind} @var{xwidget} @var{arg})
 This event is sent whenever some kind of update occurs in
-@var{xwidget}.  There are several types of updates, which are
-identified by @var{kind}.
-
-@cindex @code{load-changed} xwidget events
-An xwidget event with @var{kind} set to @code{load-changed} indicates
-that the @var{xwidget} has reached a particular point of the
-page-loading process.  When these events are sent, @var{arg} will
-contain a string that futher describes the status of the widget.
-
-@cindex @samp{"load-finished"} in xwidgets
-When @var{arg} is @samp{"load-finished"}, it means the xwidget has
-finished processing whatever page-loading operation that it was
-previously performing.
-
-@cindex @samp{"load-started"} in xwidgets
-Otherwise, if it is @samp{"load-started"}, then the widget has begun a
-page-loading operation.
-
-@cindex @samp{"load-redirected"} in xwidgets
-If @var{arg} is @samp{"load-redirected"}, it means the widget has
-encountered and followed a redirect during the page-loading operation.
-
-@cindex @samp{"load-committed"} in xwidgets
-If @var{arg} is @samp{"load-committed"}, then the widget has committed
-to a given URL during the page-loading operation.  This means that the
-URL is the final URL that will be rendered by @var{xwidget} during the
-current page-loading operation.
+@var{xwidget}.  There are several types of updates, identified by
+their @var{kind}.
+
+@table @code
+@cindex @code{load-changed} xwidget event
+@item load-changed
+This xwidget event indicates that the @var{xwidget} has reached a
+particular point of the page-loading process.  When these events are
+sent, @var{arg} will contain a string that futher describes the status
+of the widget:
+
+@table @samp
+@cindex @samp{load-started} in xwidgets
+@item load-started
+This means the widget has begun a page-loading operation.
+
+@cindex @samp{load-finished} in xwidgets
+@item load-finished
+This means the @var{xwidget} has finished processing whatever
+page-loading operation that it was previously performing.
+
+@cindex @samp{load-redirected} in xwidgets
+@item load-redirected
+This means the @var{xwidget} has encountered and followed a redirect
+during the page-loading operation.
+
+@cindex @samp{load-committed} in xwidgets
+@item load-committed
+This means the @var{xwidget} has committed to a given URL during the
+page-loading operation, i.e.@: the URL is the final URL that will be
+rendered by @var{xwidget} during the current page-loading operation.
+@end table
 
 @cindex @code{download-callback} xwidget events
-An event with @var{kind} set to @code{download-callback} indicates
-that a download of some kind has been completed.
+@item download-callback
+This event indicates that a download of some kind has been completed.
+@end table
 
-In these events, there can be arguments after @var{arg}, which itself
-indicates the URL that the download file was retrieved from: the first
-argument after @var{arg} indicates the MIME type of the download, as a
-string, while the second such argument contains the full file path to
-the downloaded file.
+In the above events, there can be arguments after @var{arg}, which
+itself indicates the URL from which the download file was retrieved:
+the first argument after @var{arg} indicates the MIME type of the
+download, as a string, while the second argument contains the full
+file name of the downloaded file.
 
+@table @code
 @cindex @code{download-started} xwidget events
-An event with @var{kind} set to @code{download-started} indicates that
-a download has been started.  In these events, @var{arg} contains the
-URL of the file that is currently being downloaded.
+@item download-started
+This event indicates that a download has been started.  In these
+events, @var{arg} contains the URL of the file that is currently being
+downloaded.
 
 @cindex @code{javascript-callback} xwidget events
-An event with @var{kind} set to @code{javascript-callback} contains
-JavaScript callback data.  These events are used internally by
-@code{xwidget-webkit-execute-script}.
+@item javascript-callback
+This event contains JavaScript callback data.  These events are used
+internally by @code{xwidget-webkit-execute-script}.
+@end table
 
 @cindex @code{xwidget-display-event} event
 @item (xwidget-display-event @var{xwidget})
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 60bca15..b6bd14f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6890,22 +6890,22 @@ query-on-exit flag, either @code{t} or @code{nil}.
 
 @defun xwidget-perform-lispy-event xwidget event frame
 Send an input event @var{event} to @var{xwidget}.  The precise action
-performed is platform-specific.  See @ref{Input Events}.
+performed is platform-specific.  @xref{Input Events}.
 
-You can optionally pass the frame the event was generated from via
+You can optionally pass the frame on which the event was generated via
 @var{frame}.  On X11, modifier keys in key events will not be
 considered if @var{frame} is @code{nil}, and the selected frame is not
 an X-Windows frame.
 
-On GTK, only keyboard and function key events are implemented.  Mouse,
+On GTK, only keyboard and function key events are supported.  Mouse,
 motion, and click events are dispatched to the xwidget without going
 through Lisp code, and as such shouldn't require this function to be
-sent.
+called.
 @end defun
 
 @defun xwidget-webkit-search query xwidget &optional case-insensitive 
backwards wrap-around
 Start an incremental search on the WebKit widget @var{xwidget} with
-the string @var{query} as a query.  @var{case-insensitive} denotes
+the string @var{query} as the query.  @var{case-insensitive} denotes
 whether or not the search is case-insensitive, @var{backwards}
 determines if the search is performed backwards towards the start of
 the document, and @var{wrap-around} determines whether or not the
@@ -6919,28 +6919,28 @@ To stop a search query, use 
@code{xwidget-webkit-finish-search}.
 
 @defun xwidget-webkit-next-result xwidget
 Display the next search result in @var{xwidget}.  This function will
-error unless a search query has already been started in @var{xwidget}
-through @code{xwidget-webkit-search}.
+signal an error if a search query has not been already started in
+@var{xwidget} through @code{xwidget-webkit-search}.
 
 If @code{wrap-around} was non-nil when @code{xwidget-webkit-search}
 was called, then the search will restart from the beginning of the
-document if the end is reached.
+document when its end is reached.
 @end defun
 
 @defun xwidget-webkit-previous-result xwidget
 Display the previous search result in @var{xwidget}.  This function
-will error unless a search query has already been started in
+signals an error if a search query has not been already started in
 @var{xwidget} through @code{xwidget-webkit-search}.
 
 If @code{wrap-around} was non-nil when @code{xwidget-webkit-search}
 was called, then the search will restart from the end of the
-document if the beginning is reached.
+document when its beginning is reached.
 @end defun
 
 @defun xwidget-webkit-finish-search xwidget
 Finish a search operation started with @code{xwidget-webkit-search} in
-@var{xwidget}.  If there is no query currently ongoing, then this
-function will error.
+@var{xwidget}.  If there is no query currently ongoing, this function
+signals an error.
 @end defun
 
 @node Buttons
diff --git a/etc/NEWS b/etc/NEWS
index b14f9a2..4c1513a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -498,16 +498,16 @@ This is a convenience function to extract the field data 
from
 ** Xwidgets
 
 +++
-*** New minor mode `xwidget-webkit-edit-mode'.
+*** New minor mode 'xwidget-webkit-edit-mode'.
 When this mode is enabled, self-inserting characters and other common
 web browser shotcut keys are redefined to send themselves to the
 WebKit widget.
 
 +++
-*** New minor mode `xwidget-webkit-isearch-mode'.
+*** New minor mode 'xwidget-webkit-isearch-mode'.
 This mode acts similarly to incremental search, and allows to search
 the contents of a WebKit widget.  In xwidget-webkit mode, it is bound
-to `C-s' and `C-r'.
+to 'C-s' and 'C-r'.
 
 ---
 *** On X11, the WebKit inspector is now available inside xwidgets.
@@ -516,8 +516,8 @@ Element".
 
 ---
 *** "Open in New Window" in a WebKit widget's context menu now works.
-The newly created buffer will be displayed via display-buffer, which
-can be customized through the usual mechanism of display-buffer-alist
+The newly created buffer will be displayed via 'display-buffer', which
+can be customized through the usual mechanism of 'display-buffer-alist'
 and friends.
 
 
@@ -745,13 +745,15 @@ an exact match, then the lowercased '[menu-bar foo\ bar]' 
and finally
 when converting menus to use 'easy-menu-define'.
 
 +++
-** The function `make-xwidget' now accepts an optional RELATED argument.
+** xwidgets
+
+*** The function 'make-xwidget' now accepts an optional RELATED argument.
 This argument is used as another widget for the newly created WebKit
 widget to share settings and subprocesses with.  It must be another
 WebKit widget.
 
 +++
-** New function `xwidget-perform-lispy-event'.
+*** New function 'xwidget-perform-lispy-event'.
 This function allows you to send events to xwidgets.  Usually, some
 equivalent of the event will be sent, but there is no guarantee of
 what the widget will actually receive.
@@ -759,23 +761,23 @@ what the widget will actually receive.
 On GTK+, only key and function key events are implemented.
 
 +++
-** New functions for performing searches on WebKit xwidgets.
-Some new functions, such as `xwidget-webkit-search', have been added
+*** New functions for performing searches on WebKit xwidgets.
+Some new functions, such as 'xwidget-webkit-search', have been added
 for performing searches on WebKit xwidgets.
 
 +++
-** `load-changed' xwidget events are now more detailed.
+*** 'load-changed' xwidget events are now more detailed.
 In particular, they can now have different arguments based on the
-state of the WebKit widget.  `load-finished' is sent when a load has
-completed, `load-started' when a load first starts, `load-redirected'
-after a redirect, and `load-committed' when the WebKit widget first
+state of the WebKit widget.  'load-finished' is sent when a load has
+completed, 'load-started' when a load first starts, 'load-redirected'
+after a redirect, and 'load-committed' when the WebKit widget first
 commits to the load.
 
 +++
-** New event type `xwidget-display-event'.
+*** New event type 'xwidget-display-event'.
 These events are sent whenever an xwidget requests that Emacs display
-another.  The only argument to this event is the xwidget that should
-be displayed.
+another xwidget.  The only argument to this event is the xwidget that
+should be displayed.
 
 
 * Changes in Emacs 29.1 on Non-Free Operating Systems
diff --git a/lisp/xwidget.el b/lisp/xwidget.el
index 1e169d5..4bd2be2 100644
--- a/lisp/xwidget.el
+++ b/lisp/xwidget.el
@@ -926,18 +926,17 @@ With argument, add COUNT copies of CHAR."
 (define-minor-mode xwidget-webkit-isearch-mode
   "Minor mode for performing incremental search inside WebKit buffers.
 
-An attempt was made for this to resemble regular incremental
-search, but it suffers from several limitations, such as not
-supporting recursive edits.
+This resembles the regular incremental search, but it does not
+support recursive edits.
 
-If this mode is enabled with `C-r', then the search will default
-to being performed in reverse direction.
+If this mode is activated with 
`\\<xwidget-webkit-isearch-mode-map>\\[xwidget-webkit-isearch-backward]', then 
the search will by default
+start in the reverse direction.
 
 To navigate around the search results, type
-\\[xwidget-webkit-isearch-forward] to move forward, and
-\\[xwidget-webkit-isearch-backward] to move backward.
+\\<xwidget-webkit-isearch-mode-map>\\[xwidget-webkit-isearch-forward] to move 
forward, and
+\\<xwidget-webkit-isearch-mode-map>\\[xwidget-webkit-isearch-backward] to move 
backward.
 
-Press \\[xwidget-webkit-isearch-exit] to exit incremental search."
+Press \\<xwidget-webkit-isearch-mode-map>\\[xwidget-webkit-isearch-exit] to 
exit incremental search."
   :keymap xwidget-webkit-isearch-mode-map
   (if xwidget-webkit-isearch-mode
       (progn
diff --git a/src/keyboard.c b/src/keyboard.c
index c4a5671..de9805d 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -6123,28 +6123,20 @@ make_lispy_event (struct input_event *event)
 
 #ifdef HAVE_DBUS
     case DBUS_EVENT:
-      {
-       return Fcons (Qdbus_event, event->arg);
-      }
+      return Fcons (Qdbus_event, event->arg);
 #endif /* HAVE_DBUS */
 
 #ifdef THREADS_ENABLED
     case THREAD_EVENT:
-      {
-       return Fcons (Qthread_event, event->arg);
-      }
+      return Fcons (Qthread_event, event->arg);
 #endif /* THREADS_ENABLED */
 
 #ifdef HAVE_XWIDGETS
     case XWIDGET_EVENT:
-      {
-        return Fcons (Qxwidget_event, event->arg);
-      }
+      return Fcons (Qxwidget_event, event->arg);
 
     case XWIDGET_DISPLAY_EVENT:
-      {
-       return list2 (Qxwidget_display_event, event->arg);
-      }
+      return list2 (Qxwidget_display_event, event->arg);
 #endif
 
 #ifdef USE_FILE_NOTIFY
diff --git a/src/xwidget.c b/src/xwidget.c
index 78a3860..66d84ee 100644
--- a/src/xwidget.c
+++ b/src/xwidget.c
@@ -174,8 +174,7 @@ fails.  */)
 
              /* webkitgtk uses GSubprocess which sets sigaction causing
                 Emacs to not catch SIGCHLD with its usual handle setup in
-                catch_child_signal().  This resets the SIGCHLD
-                sigaction.  */
+                'catch_child_signal'.  This resets the SIGCHLD sigaction.  */
              struct sigaction old_action;
              sigaction (SIGCHLD, NULL, &old_action);
              webkit_web_view_load_uri (WEBKIT_WEB_VIEW (xw->widget_osr),
@@ -188,7 +187,7 @@ fails.  */)
              xw->widget_osr = webkit_web_view_new_with_related_view 
(related_view);
            }
 
-         /* Enable the developer extras */
+         /* Enable the developer extras.  */
          settings = webkit_web_view_get_settings (WEBKIT_WEB_VIEW 
(xw->widget_osr));
          g_object_set (G_OBJECT (settings), "enable-developer-extras", TRUE, 
NULL);
        }
@@ -262,9 +261,7 @@ set_widget_if_text_view (GtkWidget *widget, void *data)
   GtkWidget **pointer = data;
 
   if (GTK_IS_TEXT_VIEW (widget))
-    {
-      *pointer = widget;
-    }
+    *pointer = widget;
 }
 #endif
 
@@ -272,9 +269,9 @@ DEFUN ("xwidget-perform-lispy-event",
        Fxwidget_perform_lispy_event, Sxwidget_perform_lispy_event,
        2, 3, 0, doc: /* Send a lispy event to XWIDGET.
 EVENT should be the event that will be sent.  FRAME should be the
-frame which generated the event, or nil.  On X11, modifier keys will
-not be processed if FRAME is nil and the selected frame is not an
-X-Windows frame.  */)
+frame which generated the event, and defaults to the selected frame.
+On X11, modifier keys will not be processed if FRAME is nil and the
+selected frame is not an X-Windows frame.  */)
   (Lisp_Object xwidget, Lisp_Object event, Lisp_Object frame)
 {
   struct xwidget *xw;
@@ -503,39 +500,39 @@ find_widget (GtkWidget *widget,
     {
       window = gtk_widget_get_window (widget);
       while (window != gtk_widget_get_window (gtk_widget_get_parent (widget)))
-        {
-          gint tx, ty, twidth, theight;
+       {
+         gint tx, ty, twidth, theight;
 
          if (!window)
            return;
 
-          twidth = gdk_window_get_width (window);
-          theight = gdk_window_get_height (window);
+         twidth = gdk_window_get_width (window);
+         theight = gdk_window_get_height (window);
 
-          if (new_allocation.x < 0)
-            {
-              new_allocation.width += new_allocation.x;
-              new_allocation.x = 0;
-            }
+         if (new_allocation.x < 0)
+           {
+             new_allocation.width += new_allocation.x;
+             new_allocation.x = 0;
+           }
 
-          if (new_allocation.y < 0)
-            {
-              new_allocation.height += new_allocation.y;
-              new_allocation.y = 0;
-            }
+         if (new_allocation.y < 0)
+           {
+             new_allocation.height += new_allocation.y;
+             new_allocation.y = 0;
+           }
 
-          if (new_allocation.x + new_allocation.width > twidth)
-            new_allocation.width = twidth - new_allocation.x;
-          if (new_allocation.y + new_allocation.height > theight)
-            new_allocation.height = theight - new_allocation.y;
+         if (new_allocation.x + new_allocation.width > twidth)
+           new_allocation.width = twidth - new_allocation.x;
+         if (new_allocation.y + new_allocation.height > theight)
+           new_allocation.height = theight - new_allocation.y;
 
-          gdk_window_get_position (window, &tx, &ty);
-          new_allocation.x += tx;
-          x_offset += tx;
-          new_allocation.y += ty;
-          y_offset += ty;
+         gdk_window_get_position (window, &tx, &ty);
+         new_allocation.x += tx;
+         x_offset += tx;
+         new_allocation.y += ty;
+         y_offset += ty;
 
-          window = gdk_window_get_parent (window);
+         window = gdk_window_get_parent (window);
        }
     }
 
@@ -543,35 +540,33 @@ find_widget (GtkWidget *widget,
       (data->x < new_allocation.x + new_allocation.width) &&
       (data->y < new_allocation.y + new_allocation.height))
     {
-      /* First, check if the drag is in a valid drop site in
-       * one of our children
-       */
+      /* First, check if the drag is in a valid drop site in one of
+        our children.  */
       if (GTK_IS_CONTAINER (widget))
-        {
-          struct widget_search_data new_data = *data;
+       {
+         struct widget_search_data new_data = *data;
 
-          new_data.x -= x_offset;
-          new_data.y -= y_offset;
-          new_data.foundp = false;
-          new_data.first = false;
+         new_data.x -= x_offset;
+         new_data.y -= y_offset;
+         new_data.foundp = false;
+         new_data.first = false;
 
-          gtk_container_forall (GTK_CONTAINER (widget),
-                                find_widget_cb, &new_data);
+         gtk_container_forall (GTK_CONTAINER (widget),
+                               find_widget_cb, &new_data);
 
-          data->foundp = new_data.foundp;
-          if (data->foundp)
-            data->data = new_data.data;
-        }
+         data->foundp = new_data.foundp;
+         if (data->foundp)
+           data->data = new_data.data;
+       }
 
-      /* If not, and this widget is registered as a drop site, check to
-       * emit "drag_motion" to check if we are actually in
-       * a drop site.
-       */
+      /* If not, and this widget is registered as a drop site, check
+        to emit "drag_motion" to check if we are actually in a drop
+        site.  */
       if (!data->foundp)
-        {
-          data->foundp = true;
-          data->data = widget;
-        }
+       {
+         data->foundp = true;
+         data->data = widget;
+       }
     }
 }
 
@@ -673,7 +668,7 @@ xwidget_button_1 (struct xwidget_view *view,
 
   xg_event->any.window = gtk_widget_get_window (target);
   g_object_ref (xg_event->any.window); /* The window will be unrefed
-                                         later by gdk_event_free. */
+                                         later by gdk_event_free.  */
 
   xg_event->button.x = x;
   xg_event->button.x_root = x;
@@ -711,7 +706,7 @@ xwidget_button (struct xwidget_view *view,
 
       xg_event->any.window = gtk_widget_get_window (target);
       g_object_ref (xg_event->any.window); /* The window will be unrefed
-                                             later by gdk_event_free. */
+                                             later by gdk_event_free.  */
       if (button == 4)
        xg_event->scroll.direction = GDK_SCROLL_UP;
       else if (button == 5)
@@ -741,9 +736,11 @@ xwidget_button (struct xwidget_view *view,
 void
 xwidget_motion_or_crossing (struct xwidget_view *view, const XEvent *event)
 {
-  GdkEvent *xg_event = gdk_event_new (event->type == MotionNotify ? 
GDK_MOTION_NOTIFY :
-                                     (event->type == LeaveNotify ? 
GDK_LEAVE_NOTIFY :
-                                      GDK_ENTER_NOTIFY));
+  GdkEvent *xg_event = gdk_event_new (event->type == MotionNotify
+                                     ? GDK_MOTION_NOTIFY
+                                     : (event->type == LeaveNotify
+                                        ? GDK_LEAVE_NOTIFY
+                                        : GDK_ENTER_NOTIFY));
   struct xwidget *model = XXWIDGET (view->model);
   int x;
   int y;
@@ -761,7 +758,7 @@ xwidget_motion_or_crossing (struct xwidget_view *view, 
const XEvent *event)
 
   xg_event->any.window = gtk_widget_get_window (target);
   g_object_ref (xg_event->any.window); /* The window will be unrefed
-                                         later by gdk_event_free. */
+                                         later by gdk_event_free.  */
 
   if (event->type == MotionNotify)
     {
@@ -2302,9 +2299,7 @@ kill_frame_xwidget_views (struct frame *f)
     }
 
   for (; CONSP (rem); rem = XCDR (rem))
-    {
-      Fdelete_xwidget_view (XCAR (rem));
-    }
+    Fdelete_xwidget_view (XCAR (rem));
 }
 #endif