Update include/ comments to Doxygen formatting (see issue #3384)

See related guidelines in the issue.
This commit is contained in:
Marshall Greenblatt
2022-08-31 22:03:04 -04:00
parent 7b352159df
commit d7a153bdd4
235 changed files with 11484 additions and 11274 deletions

View File

@ -33,7 +33,7 @@
// by hand. See the translator.README.txt file in the tools directory for
// more information.
//
// $hash=84440a43cf4be6728b51919e65c5f33e5736c502$
// $hash=7c6894aae3e508aaa42a376532328316d9bd509c$
//
#ifndef CEF_INCLUDE_CAPI_CEF_APP_CAPI_H_
@ -54,25 +54,26 @@ extern "C" {
struct _cef_app_t;
///
// Implement this structure to provide handler implementations. Methods will be
// called by the process and/or thread indicated.
/// Implement this structure to provide handler implementations. Methods will be
/// called by the process and/or thread indicated.
///
typedef struct _cef_app_t {
///
// Base structure.
/// Base structure.
///
cef_base_ref_counted_t base;
///
// Provides an opportunity to view and/or modify command-line arguments before
// processing by CEF and Chromium. The |process_type| value will be NULL for
// the browser process. Do not keep a reference to the cef_command_line_t
// object passed to this function. The CefSettings.command_line_args_disabled
// value can be used to start with an NULL command-line object. Any values
// specified in CefSettings that equate to command-line arguments will be set
// before this function is called. Be cautious when using this function to
// modify command-line arguments for non-browser processes as this may result
// in undefined behavior including crashes.
/// Provides an opportunity to view and/or modify command-line arguments
/// before processing by CEF and Chromium. The |process_type| value will be
/// NULL for the browser process. Do not keep a reference to the
/// cef_command_line_t object passed to this function. The
/// cef_settings_t.command_line_args_disabled value can be used to start with
/// an NULL command-line object. Any values specified in CefSettings that
/// equate to command-line arguments will be set before this function is
/// called. Be cautious when using this function to modify command-line
/// arguments for non-browser processes as this may result in undefined
/// behavior including crashes.
///
void(CEF_CALLBACK* on_before_command_line_processing)(
struct _cef_app_t* self,
@ -80,61 +81,62 @@ typedef struct _cef_app_t {
struct _cef_command_line_t* command_line);
///
// Provides an opportunity to register custom schemes. Do not keep a reference
// to the |registrar| object. This function is called on the main thread for
// each process and the registered schemes should be the same across all
// processes.
/// Provides an opportunity to register custom schemes. Do not keep a
/// reference to the |registrar| object. This function is called on the main
/// thread for each process and the registered schemes should be the same
/// across all processes.
///
void(CEF_CALLBACK* on_register_custom_schemes)(
struct _cef_app_t* self,
struct _cef_scheme_registrar_t* registrar);
///
// Return the handler for resource bundle events. If
// CefSettings.pack_loading_disabled is true (1) a handler must be returned.
// If no handler is returned resources will be loaded from pack files. This
// function is called by the browser and render processes on multiple threads.
/// Return the handler for resource bundle events. If
/// cef_settings_t.pack_loading_disabled is true (1) a handler must be
/// returned. If no handler is returned resources will be loaded from pack
/// files. This function is called by the browser and render processes on
/// multiple threads.
///
struct _cef_resource_bundle_handler_t*(
CEF_CALLBACK* get_resource_bundle_handler)(struct _cef_app_t* self);
///
// Return the handler for functionality specific to the browser process. This
// function is called on multiple threads in the browser process.
/// Return the handler for functionality specific to the browser process. This
/// function is called on multiple threads in the browser process.
///
struct _cef_browser_process_handler_t*(
CEF_CALLBACK* get_browser_process_handler)(struct _cef_app_t* self);
///
// Return the handler for functionality specific to the render process. This
// function is called on the render process main thread.
/// Return the handler for functionality specific to the render process. This
/// function is called on the render process main thread.
///
struct _cef_render_process_handler_t*(
CEF_CALLBACK* get_render_process_handler)(struct _cef_app_t* self);
} cef_app_t;
///
// This function should be called from the application entry point function to
// execute a secondary process. It can be used to run secondary processes from
// the browser client executable (default behavior) or from a separate
// executable specified by the CefSettings.browser_subprocess_path value. If
// called for the browser process (identified by no "type" command-line value)
// it will return immediately with a value of -1. If called for a recognized
// secondary process it will block until the process should exit and then return
// the process exit code. The |application| parameter may be NULL. The
// |windows_sandbox_info| parameter is only used on Windows and may be NULL (see
// cef_sandbox_win.h for details).
/// This function should be called from the application entry point function to
/// execute a secondary process. It can be used to run secondary processes from
/// the browser client executable (default behavior) or from a separate
/// executable specified by the cef_settings_t.browser_subprocess_path value. If
/// called for the browser process (identified by no "type" command-line value)
/// it will return immediately with a value of -1. If called for a recognized
/// secondary process it will block until the process should exit and then
/// return the process exit code. The |application| parameter may be NULL. The
/// |windows_sandbox_info| parameter is only used on Windows and may be NULL
/// (see cef_sandbox_win.h for details).
///
CEF_EXPORT int cef_execute_process(const cef_main_args_t* args,
cef_app_t* application,
void* windows_sandbox_info);
///
// This function should be called on the main application thread to initialize
// the CEF browser process. The |application| parameter may be NULL. A return
// value of true (1) indicates that it succeeded and false (0) indicates that it
// failed. The |windows_sandbox_info| parameter is only used on Windows and may
// be NULL (see cef_sandbox_win.h for details).
/// This function should be called on the main application thread to initialize
/// the CEF browser process. The |application| parameter may be NULL. A return
/// value of true (1) indicates that it succeeded and false (0) indicates that
/// it failed. The |windows_sandbox_info| parameter is only used on Windows and
/// may be NULL (see cef_sandbox_win.h for details).
///
CEF_EXPORT int cef_initialize(const cef_main_args_t* args,
const struct _cef_settings_t* settings,
@ -142,55 +144,55 @@ CEF_EXPORT int cef_initialize(const cef_main_args_t* args,
void* windows_sandbox_info);
///
// This function should be called on the main application thread to shut down
// the CEF browser process before the application exits.
/// This function should be called on the main application thread to shut down
/// the CEF browser process before the application exits.
///
CEF_EXPORT void cef_shutdown(void);
///
// Perform a single iteration of CEF message loop processing. This function is
// provided for cases where the CEF message loop must be integrated into an
// existing application message loop. Use of this function is not recommended
// for most users; use either the cef_run_message_loop() function or
// CefSettings.multi_threaded_message_loop if possible. When using this function
// care must be taken to balance performance against excessive CPU usage. It is
// recommended to enable the CefSettings.external_message_pump option when using
// this function so that
// cef_browser_process_handler_t::on_schedule_message_pump_work() callbacks can
// facilitate the scheduling process. This function should only be called on the
// main application thread and only if cef_initialize() is called with a
// CefSettings.multi_threaded_message_loop value of false (0). This function
// will not block.
/// Perform a single iteration of CEF message loop processing. This function is
/// provided for cases where the CEF message loop must be integrated into an
/// existing application message loop. Use of this function is not recommended
/// for most users; use either the cef_run_message_loop() function or
/// cef_settings_t.multi_threaded_message_loop if possible. When using this
/// function care must be taken to balance performance against excessive CPU
/// usage. It is recommended to enable the cef_settings_t.external_message_pump
/// option when using this function so that
/// cef_browser_process_handler_t::on_schedule_message_pump_work() callbacks can
/// facilitate the scheduling process. This function should only be called on
/// the main application thread and only if cef_initialize() is called with a
/// cef_settings_t.multi_threaded_message_loop value of false (0). This function
/// will not block.
///
CEF_EXPORT void cef_do_message_loop_work(void);
///
// Run the CEF message loop. Use this function instead of an application-
// provided message loop to get the best balance between performance and CPU
// usage. This function should only be called on the main application thread and
// only if cef_initialize() is called with a
// CefSettings.multi_threaded_message_loop value of false (0). This function
// will block until a quit message is received by the system.
/// Run the CEF message loop. Use this function instead of an application-
/// provided message loop to get the best balance between performance and CPU
/// usage. This function should only be called on the main application thread
/// and only if cef_initialize() is called with a
/// cef_settings_t.multi_threaded_message_loop value of false (0). This function
/// will block until a quit message is received by the system.
///
CEF_EXPORT void cef_run_message_loop(void);
///
// Quit the CEF message loop that was started by calling cef_run_message_loop().
// This function should only be called on the main application thread and only
// if cef_run_message_loop() was used.
/// Quit the CEF message loop that was started by calling
/// cef_run_message_loop(). This function should only be called on the main
/// application thread and only if cef_run_message_loop() was used.
///
CEF_EXPORT void cef_quit_message_loop(void);
///
// Set to true (1) before calling Windows APIs like TrackPopupMenu that enter a
// modal message loop. Set to false (0) after exiting the modal message loop.
/// Set to true (1) before calling Windows APIs like TrackPopupMenu that enter a
/// modal message loop. Set to false (0) after exiting the modal message loop.
///
CEF_EXPORT void cef_set_osmodal_loop(int osModalLoop);
///
// Call during process startup to enable High-DPI support on Windows 7 or newer.
// Older versions of Windows should be left DPI-unaware because they do not
// support DirectWrite and GDI fonts are kerned very badly.
/// Call during process startup to enable High-DPI support on Windows 7 or
/// newer. Older versions of Windows should be left DPI-unaware because they do
/// not support DirectWrite and GDI fonts are kerned very badly.
///
CEF_EXPORT void cef_enable_highdpi_support(void);