From: Stefan Kangas Date: Thu, 17 Apr 2025 05:56:55 +0000 (+0200) Subject: Delete duplicate docstrings in PGTK build X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=58758c22b9f940551acb10e7a57bb86a1ead8485;p=emacs.git Delete duplicate docstrings in PGTK build * src/pgtkfns.c (Fx_export_frames, Fx_create_frame) (Fx_server_max_request_size, Fx_display_screens, Fx_display_mm_height) (Fx_display_mm_width, Fx_display_backing_store, Fx_display_visual_class) (Fx_display_save_under, Fx_open_connection, Fx_close_connection) (Fx_display_list, Fxw_color_defined_p, Fxw_color_values) (Fxw_display_color_p, Fx_display_grayscale_p, Fx_display_pixel_width) (Fx_display_pixel_height, Fx_display_planes, Fx_display_color_cells) (Fx_show_tip, Fx_hide_tip, Fx_file_dialog, Fx_select_font): Replace duplicate docstrings with "SKIP" marker. See the comment in doc.c. * src/xfns.c (Fx_server_max_request_size, Fx_display_screens) (Fx_display_backing_store, Fx_display_visual_class, Fx_file_dialog): Update docstrings with details about the PGTK build. (cherry picked from commit 4fcba8456e897cc77d1825e696aacb446ce45405) --- diff --git a/src/pgtkfns.c b/src/pgtkfns.c index 6231ef1cb48..e979b84d2e6 100644 --- a/src/pgtkfns.c +++ b/src/pgtkfns.c @@ -879,15 +879,7 @@ pgtk_set_scroll_bar_background (struct frame *f, Lisp_Object new_value, DEFUN ("x-export-frames", Fx_export_frames, Sx_export_frames, 0, 2, 0, - doc: /* Return image data of FRAMES in TYPE format. -FRAMES should be nil (the selected frame), a frame, or a list of -frames (each of which corresponds to one page). Each frame should be -visible. Optional arg TYPE should be either `pdf' (default), `png', -`postscript', or `svg'. Supported types are determined by the -compile-time configuration of cairo. - -Note: Text drawn with the `x' font backend is shown with hollow boxes -unless TYPE is `png'. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object frames, Lisp_Object type) { Lisp_Object rest, tmp; @@ -1178,14 +1170,7 @@ scale factor. */) } DEFUN ("x-create-frame", Fx_create_frame, Sx_create_frame, 1, 1, 0, - doc: /* Make a new X window, which is called a "frame" in Emacs terms. -Return an Emacs frame object. PARMS is an alist of frame parameters. -If the parameters specify that the frame should not have a minibuffer, -and do not specify a specific minibuffer window to use, then -`default-minibuffer-frame' must be a frame whose minibuffer can be -shared by the new frame. - -This function is an internal primitive--use `make-frame' instead. */ ) + doc: /* SKIP: real doc in xfns.c. */ ) (Lisp_Object parms) { struct frame *f; @@ -2003,7 +1988,7 @@ DEFUN ("pgtk-set-resource", Fpgtk_set_resource, Spgtk_set_resource, 2, 2, 0, DEFUN ("x-server-max-request-size", Fx_server_max_request_size, Sx_server_max_request_size, 0, 1, 0, - doc: /* This function is a no-op. It is only present for completeness. */ ) + doc: /* SKIP: real doc in xfns.c. */ ) (Lisp_Object terminal) { check_pgtk_display_info (terminal); @@ -2014,13 +1999,7 @@ DEFUN ("x-server-max-request-size", Fx_server_max_request_size, Sx_server_max_re DEFUN ("x-display-screens", Fx_display_screens, Sx_display_screens, 0, 1, 0, - doc: /* Return the number of screens on the display server TERMINAL. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. - -Note: "screen" here is not in X11's. For the number of physical monitors, -use `(length \(display-monitor-attributes-list TERMINAL))' instead. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { check_pgtk_display_info (terminal); @@ -2029,14 +2008,7 @@ use `(length \(display-monitor-attributes-list TERMINAL))' instead. */) DEFUN ("x-display-mm-height", Fx_display_mm_height, Sx_display_mm_height, 0, 1, 0, - doc: /* Return the height in millimeters of the display TERMINAL. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. - -On \"multi-monitor\" setups this refers to the height in millimeters for -all physical monitors associated with TERMINAL. To get information -for each physical monitor, use `display-monitor-attributes-list'. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { struct pgtk_display_info *dpyinfo = check_pgtk_display_info (terminal); @@ -2070,14 +2042,7 @@ for each physical monitor, use `display-monitor-attributes-list'. */) DEFUN ("x-display-mm-width", Fx_display_mm_width, Sx_display_mm_width, 0, 1, 0, - doc: /* Return the width in millimeters of the display TERMINAL. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. - -On \"multi-monitor\" setups this refers to the width in millimeters for -all physical monitors associated with TERMINAL. To get information -for each physical monitor, use `display-monitor-attributes-list'. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { struct pgtk_display_info *dpyinfo = check_pgtk_display_info (terminal); @@ -2111,11 +2076,7 @@ for each physical monitor, use `display-monitor-attributes-list'. */) DEFUN ("x-display-backing-store", Fx_display_backing_store, Sx_display_backing_store, 0, 1, 0, - doc: /* Return an indication of whether the display TERMINAL does backing store. -The value may be `buffered', `retained', or `non-retained'. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { check_pgtk_display_info (terminal); @@ -2124,15 +2085,7 @@ If omitted or nil, that stands for the selected frame's display. */) DEFUN ("x-display-visual-class", Fx_display_visual_class, Sx_display_visual_class, 0, 1, 0, - doc: /* Return the visual class of the display TERMINAL. -The value is one of the symbols `static-gray', `gray-scale', -`static-color', `pseudo-color', `true-color', or `direct-color'. - -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. - -On PGTK, always return true-color. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { return Qtrue_color; @@ -2140,10 +2093,7 @@ On PGTK, always return true-color. */) DEFUN ("x-display-save-under", Fx_display_save_under, Sx_display_save_under, 0, 1, 0, - doc: /* Return t if TERMINAL supports the save-under feature. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { check_pgtk_display_info (terminal); @@ -2152,11 +2102,7 @@ If omitted or nil, that stands for the selected frame's display. */) DEFUN ("x-open-connection", Fx_open_connection, Sx_open_connection, 1, 3, 0, - doc: /* Open a connection to a display server. -DISPLAY is the name of the display to connect to. -Optional second arg XRM-STRING is a string of resources in xrdb format. -If the optional third arg MUST-SUCCEED is non-nil, -terminate Emacs if we can't open the connection. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object display, Lisp_Object resource_string, Lisp_Object must_succeed) { struct pgtk_display_info *dpyinfo; @@ -2180,10 +2126,7 @@ terminate Emacs if we can't open the connection. */) DEFUN ("x-close-connection", Fx_close_connection, Sx_close_connection, 1, 1, 0, - doc: /* Close the connection to TERMINAL's display server. -For TERMINAL, specify a terminal object, a frame or a display name (a -string). If TERMINAL is nil, that stands for the selected frame's -terminal. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { struct pgtk_display_info *dpyinfo = check_pgtk_display_info (terminal); @@ -2198,7 +2141,7 @@ terminal. */) DEFUN ("x-display-list", Fx_display_list, Sx_display_list, 0, 0, 0, - doc: /* Return the list of display names that Emacs has connections to. */) + doc: /* SKIP: real doc in xfns.c. */) (void) { Lisp_Object result = Qnil; @@ -2306,7 +2249,7 @@ pgtk_get_focus_frame (struct frame *frame) } DEFUN ("xw-color-defined-p", Fxw_color_defined_p, Sxw_color_defined_p, 1, 2, 0, - doc: /* Internal function called by `color-defined-p', which see. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object color, Lisp_Object frame) { Emacs_Color col; @@ -2322,7 +2265,7 @@ DEFUN ("xw-color-defined-p", Fxw_color_defined_p, Sxw_color_defined_p, 1, 2, 0, DEFUN ("xw-color-values", Fxw_color_values, Sxw_color_values, 1, 2, 0, - doc: /* Internal function called by `color-values', which see. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object color, Lisp_Object frame) { Emacs_Color col; @@ -2337,7 +2280,7 @@ DEFUN ("xw-color-values", Fxw_color_values, Sxw_color_values, 1, 2, 0, } DEFUN ("xw-display-color-p", Fxw_display_color_p, Sxw_display_color_p, 0, 1, 0, - doc: /* Internal function called by `display-color-p', which see. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { check_pgtk_display_info (terminal); @@ -2345,25 +2288,14 @@ DEFUN ("xw-display-color-p", Fxw_display_color_p, Sxw_display_color_p, 0, 1, 0, } DEFUN ("x-display-grayscale-p", Fx_display_grayscale_p, Sx_display_grayscale_p, 0, 1, 0, - doc: /* Return t if the display supports shades of gray. -Note that color displays do support shades of gray. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { return Qnil; } DEFUN ("x-display-pixel-width", Fx_display_pixel_width, Sx_display_pixel_width, 0, 1, 0, - doc: /* Return the width in pixels of the display TERMINAL. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. - -On \"multi-monitor\" setups this refers to the pixel width for all -physical monitors associated with TERMINAL. To get information for -each physical monitor, use `display-monitor-attributes-list'. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { struct pgtk_display_info *dpyinfo = check_pgtk_display_info (terminal); @@ -2401,14 +2333,7 @@ each physical monitor, use `display-monitor-attributes-list'. */) } DEFUN ("x-display-pixel-height", Fx_display_pixel_height, Sx_display_pixel_height, 0, 1, 0, - doc: /* Return the height in pixels of the display TERMINAL. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. - -On \"multi-monitor\" setups this refers to the pixel height for all -physical monitors associated with TERMINAL. To get information for -each physical monitor, use `display-monitor-attributes-list'. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { struct pgtk_display_info *dpyinfo = check_pgtk_display_info (terminal); @@ -2574,10 +2499,7 @@ pgtk_frame_scale_factor (struct frame *f) } DEFUN ("x-display-planes", Fx_display_planes, Sx_display_planes, 0, 1, 0, - doc: /* Return the number of bitplanes of the display TERMINAL. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { check_pgtk_display_info (terminal); @@ -2586,10 +2508,7 @@ If omitted or nil, that stands for the selected frame's display. */) DEFUN ("x-display-color-cells", Fx_display_color_cells, Sx_display_color_cells, 0, 1, 0, - doc: /* Returns the number of color cells of the display TERMINAL. -The optional argument TERMINAL specifies which display to ask about. -TERMINAL should be a terminal object, a frame or a display name (a string). -If omitted or nil, that stands for the selected frame's display. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object terminal) { struct pgtk_display_info *dpyinfo = check_pgtk_display_info (terminal); @@ -3071,36 +2990,7 @@ pgtk_hide_tip (bool delete) } DEFUN ("x-show-tip", Fx_show_tip, Sx_show_tip, 1, 6, 0, - doc: /* Show STRING in a "tooltip" window on frame FRAME. -A tooltip window is a small X window displaying a string. - -This is an internal function; Lisp code should call `tooltip-show'. - -FRAME nil or omitted means use the selected frame. - -PARMS is an optional list of frame parameters which can be used to -change the tooltip's appearance. - -Automatically hide the tooltip after TIMEOUT seconds. TIMEOUT nil -means use the default timeout from the `x-show-tooltip-timeout' -variable. - -If the list of frame parameters PARMS contains a `left' parameter, -display the tooltip at that x-position. If the list of frame parameters -PARMS contains no `left' but a `right' parameter, display the tooltip -right-adjusted at that x-position. Otherwise display it at the -x-position of the mouse, with offset DX added (default is 5 if DX isn't -specified). - -Likewise for the y-position: If a `top' frame parameter is specified, it -determines the position of the upper edge of the tooltip window. If a -`bottom' parameter but no `top' frame parameter is specified, it -determines the position of the lower edge of the tooltip window. -Otherwise display the tooltip window at the y-position of the mouse, -with offset DY added (default is -10). - -A tooltip's maximum size is specified by `x-max-tooltip-size'. -Text larger than the specified size is clipped. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object string, Lisp_Object frame, Lisp_Object parms, Lisp_Object timeout, Lisp_Object dx, Lisp_Object dy) { @@ -3385,8 +3275,7 @@ Text larger than the specified size is clipped. */) DEFUN ("x-hide-tip", Fx_hide_tip, Sx_hide_tip, 0, 0, 0, - doc: /* Hide the current tooltip window, if there is any. -Value is t if tooltip was open, nil otherwise. */) + doc: /* SKIP: real doc in xfns.c. */) (void) { return pgtk_hide_tip (!tooltip_reuse_hidden_frame); @@ -3686,18 +3575,7 @@ clean_up_dialog (void) } DEFUN ("x-file-dialog", Fx_file_dialog, Sx_file_dialog, 2, 5, 0, - doc: /* Read file name, prompting with PROMPT in directory DIR. -Use a file selection dialog. Select DEFAULT-FILENAME in the dialog's file -selection box, if specified. If MUSTMATCH is non-nil, the returned file -or directory must exist. - -This function is defined only on PGTK, NS, MS Windows, and X Windows with the -Motif or Gtk toolkits. With the Motif toolkit, ONLY-DIR-P is ignored. -Otherwise, if ONLY-DIR-P is non-nil, the user can select only directories. -On MS Windows 7 and later, the file selection dialog "remembers" the last -directory where the user selected a file, and will open that directory -instead of DIR on subsequent invocations of this function with the same -value of DIR as in previous invocations; this is standard MS Windows behavior. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object prompt, Lisp_Object dir, Lisp_Object default_filename, Lisp_Object mustmatch, Lisp_Object only_dir_p) { @@ -3763,10 +3641,7 @@ If omitted or nil, that stands for the selected frame's display. */) } DEFUN ("x-select-font", Fx_select_font, Sx_select_font, 0, 2, 0, - doc: /* Read a font using a GTK dialog and return a font spec. - -FRAME is the frame on which to pop up the font chooser. If omitted or -nil, it defaults to the selected frame. */) + doc: /* SKIP: real doc in xfns.c. */) (Lisp_Object frame, Lisp_Object ignored) { struct frame *f = decode_window_system_frame (frame); diff --git a/src/xfns.c b/src/xfns.c index 67b15428bf0..4f7be935000 100644 --- a/src/xfns.c +++ b/src/xfns.c @@ -5715,7 +5715,7 @@ TERMINAL should be a terminal object, a frame or a display name (a string). If omitted or nil, that stands for the selected frame's display. On MS Windows, this function just returns 1. -On Nextstep, this function just returns nil. */) +On Nextstep and PGTK, this function just returns nil. */) (Lisp_Object terminal) { struct x_display_info *dpyinfo = check_x_display_info (terminal); @@ -5800,8 +5800,11 @@ The optional argument TERMINAL specifies which display to ask about. TERMINAL should be a terminal object, a frame or a display name (a string). If omitted or nil, that stands for the selected frame's display. +On PGTK and Nextstep, "screen" is in X terminology, not that of Wayland +and Nextstep, respectively. + On MS Windows, this function just returns 1. -On Nextstep, "screen" is in X terminology, not that of Nextstep. + For the number of physical monitors, use `(length \(display-monitor-attributes-list TERMINAL))' instead. */) (Lisp_Object terminal) @@ -5859,7 +5862,10 @@ TERMINAL should be a terminal object, a frame or a display name (a string). If omitted or nil, that stands for the selected frame's display. The value may be `always', `when-mapped', or `not-useful'. -On Nextstep, the value may be `buffered', `retained', or `non-retained'. + +On Nextstep and PGTK, the value may be `buffered', `retained', or +`non-retained'. + On MS Windows, this returns nothing useful. */) (Lisp_Object terminal) { @@ -5897,7 +5903,9 @@ The value is one of the symbols `static-gray', `gray-scale', The optional argument TERMINAL specifies which display to ask about. TERMINAL should a terminal object, a frame or a display name (a string). If omitted or nil, that stands for the selected frame's display. -\(On MS Windows, this function does not accept terminal objects.) */) +\(On MS Windows, this function does not accept terminal objects.) + +On PGTK, always return `true-color'. */) (Lisp_Object terminal) { struct x_display_info *dpyinfo = check_x_display_info (terminal); @@ -9624,9 +9632,10 @@ Use a file selection dialog. Select DEFAULT-FILENAME in the dialog's file selection box, if specified. If MUSTMATCH is non-nil, the returned file or directory must exist. -This function is defined only on NS, Haiku, MS Windows, and X Windows with the -Motif or Gtk toolkits. With the Motif toolkit, ONLY-DIR-P is ignored. +This function is defined only on PGTK, NS, Haiku, MS Windows, and X Windows with +the Motif or Gtk toolkits. With the Motif toolkit, ONLY-DIR-P is ignored. Otherwise, if ONLY-DIR-P is non-nil, the user can select only directories. + On MS Windows 7 and later, the file selection dialog "remembers" the last directory where the user selected a file, and will open that directory instead of DIR on subsequent invocations of this function with the same