core: reformat comments for functions

src/plugins/plugin-script.c

@@ -44,7 +44,7 @@ int script_option_check_license = 0;
 
 
 /*
- * plugin_script_config_read: read script configuration
+ * Reads script configuration.
  */
 
 void
@@ -65,7 +65,7 @@ plugin_script_config_read (struct t_weechat_plugin *weechat_plugin)
 }
 
 /*
- * plugin_script_config_cb: callback called when config option is changed
+ * Callback for changes on configuration option.
  */
 
 int
@@ -81,7 +81,13 @@ plugin_script_config_cb (void *data, const char *option, const char *value)
 }
 
 /*
- * plugin_script_init: initialize script plugin
+ * Initializes script plugin:
+ *   - reads configuration
+ *   - hooks config
+ *   - creates directories in WeeChat home
+ *   - hooks command, completion, hdata, infolist, signals
+ *   - parses arguments
+ *   - auto-loads scripts.
  */
 
 void
@@ -96,7 +102,7 @@ plugin_script_init (struct t_weechat_plugin *weechat_plugin,
     /* read script configuration */
     plugin_script_config_read (weechat_plugin);
 
-    /* add hook for config option */
+    /* add hook for configuration option */
     length = strlen (weechat_plugin->name) + 64;
     string = malloc (length);
     if (string)
@@ -217,9 +223,11 @@ plugin_script_init (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_valid: check if a script pointer exists
- *                      return 1 if script exists
- *                             0 if script is not found
+ * Checks if a script pointer is valid.
+ *
+ * Returns:
+ *   1: script exists
+ *   0: script is not found
  */
 
 int
@@ -243,9 +251,11 @@ plugin_script_valid (struct t_plugin_script *scripts,
 }
 
 /*
- * plugin_script_ptr2str: convert pointer to string for usage in a script
- *                        (any language)
- *                        WARNING: result has to be free() after use
+ * Converts a pointer to a string for usage in a script.
+ *
+ * Returns string with format "0x12345678".
+ *
+ * Note: result must be freed after use.
  */
 
 char *
@@ -263,7 +273,9 @@ plugin_script_ptr2str (void *pointer)
 }
 
 /*
- * plugin_script_str2ptr: convert string to pointer for usage outside script
+ * Converts a string to pointer for usage outside a script.
+ *
+ * Format of "str_pointer" is "0x12345678".
  */
 
 void *
@@ -304,7 +316,7 @@ invalid:
 }
 
 /*
- * plugin_script_auto_load: auto-load all scripts in a directory
+ * Auto-loads all scripts in a directory.
  */
 
 void
@@ -332,7 +344,9 @@ plugin_script_auto_load (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_search: search a script in list (by registered name)
+ * Searches for a script by registered name (example: "iset").
+ *
+ * Returns pointer to script, NULL if not found.
  */
 
 struct t_plugin_script *
@@ -353,8 +367,9 @@ plugin_script_search (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_search_by_full_name: search a script in list (by full name,
- *                                    for example "weeget.py")
+ * Searches for a script by full name (example: "iset.pl").
+ *
+ * Returns pointer to script, NULL if not found.
  */
 
 struct t_plugin_script *
@@ -377,7 +392,7 @@ plugin_script_search_by_full_name (struct t_plugin_script *scripts,
 }
 
 /*
- * plugin_script_search_path: search path name of a script
+ * Searches for path name of a script.
  */
 
 char *
@@ -456,7 +471,7 @@ plugin_script_search_path (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_find_pos: find position for a script (for sorting scripts list)
+ * Searches for position of script in list (to keep list sorted on name).
  */
 
 struct t_plugin_script *
@@ -475,7 +490,7 @@ plugin_script_find_pos (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_insert_sorted: insert a script in list, keeping sort on name
+ * Inserts a script in list (keeping list sorted on name).
  */
 
 void
@@ -521,7 +536,9 @@ plugin_script_insert_sorted (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_add: add a script to list of scripts
+ * Adds a script to list of scripts.
+ *
+ * Returns pointer to new script, NULL if error.
  */
 
 struct t_plugin_script *
@@ -585,9 +602,8 @@ plugin_script_add (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_set_buffer_callbacks: restore buffers callbacks (input and
- *                                     close) for buffers created by script
- *                                     plugin
+ * Restores buffers callbacks (input and close) for buffers created by script
+ * plugin.
  */
 
 void
@@ -673,8 +689,7 @@ plugin_script_set_buffer_callbacks (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_remove_buffer_callbacks: remove callbacks for a buffer (called
- *                                        when a buffer is closed by user)
+ * Removes callbacks for a buffer (called when a buffer is closed  by user).
  */
 
 void
@@ -708,7 +723,7 @@ plugin_script_remove_buffer_callbacks (struct t_plugin_script *scripts,
 }
 
 /*
- * plugin_script_remove: remove a script from list of scripts
+ * Removes a script from list of scripts.
  */
 
 void
@@ -724,7 +739,7 @@ plugin_script_remove (struct t_weechat_plugin *weechat_plugin,
     for (ptr_script_cb = script->callbacks; ptr_script_cb;
          ptr_script_cb = ptr_script_cb->next_callback)
     {
-        /* free config file */
+        /* free configuration file */
         if (ptr_script_cb->config_file)
         {
             if (weechat_config_boolean (weechat_config_get ("weechat.plugin.save_config_on_unload")))
@@ -804,7 +819,7 @@ plugin_script_remove (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_completion: complete with list of scripts
+ * Adds list of scripts to completion list.
  */
 
 void
@@ -823,7 +838,7 @@ plugin_script_completion (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_action_add: add script name for a plugin action
+ * Adds script name for a plugin action.
  */
 
 void
@@ -857,7 +872,7 @@ plugin_script_action_add (char **action_list, const char *name)
 }
 
 /*
- * plugin_script_remove_file: remove script file(s) from disk
+ * Removes script file(s) from disk.
  */
 
 void
@@ -912,15 +927,14 @@ plugin_script_remove_file (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_action_install: install some scripts (using comma separated
- *                               list)
- *                               this function does following tasks:
- *                                 1. unload script (if script is loaded)
- *                                 2. remove script file(s)
- *                                 3. move script file from "install" dir to
- *                                    language dir
- *                                 4. make link in autoload dir
- *                                 5. load script
+ * Installs some scripts (using comma separated list).
+ *
+ * This function does following tasks:
+ *   1. unloads script (if script is loaded)
+ *   2. removes script file(s)
+ *   3. moves script file from "install" dir to language dir
+ *   4. makes link in autoload dir
+ *   5. loads script.
  */
 
 void
@@ -1043,10 +1057,11 @@ plugin_script_action_install (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_action_remove: remove some scripts (using comma separated list)
- *                              this function does following tasks:
- *                                1. unload script (if script is loaded)
- *                                2. remove script file(s)
+ * Removes some scripts (using comma separated list).
+ *
+ * This function does following tasks:
+ *   1. unloads script (if script is loaded)
+ *   2. removes script file(s).
  */
 
 void
@@ -1099,7 +1114,7 @@ plugin_script_action_remove (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_display_list: print list of scripts
+ * Displays list of scripts.
  */
 
 void
@@ -1146,7 +1161,7 @@ plugin_script_display_list (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_display_short_list: print list of scripts on one line
+ * Displays list of scripts on one line.
  */
 
 void
@@ -1191,7 +1206,7 @@ plugin_script_display_short_list (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_hdata_script: return hdata for script
+ * Gets hdata for script.
  */
 
 struct t_hdata *
@@ -1226,8 +1241,11 @@ plugin_script_hdata_script (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_add_to_infolist: add a script in an infolist
- *                                return 1 if ok, 0 if error
+ * Adds a script in an infolist.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -1271,7 +1289,7 @@ plugin_script_add_to_infolist (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_infolist_list_scripts: build infolist with list of scripts
+ * Builds infolist with list of scripts.
  */
 
 struct t_infolist *
@@ -1325,7 +1343,7 @@ plugin_script_infolist_list_scripts (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_end: end script plugin
+ * Ends script plugin.
  */
 
 void
@@ -1347,7 +1365,7 @@ plugin_script_end (struct t_weechat_plugin *weechat_plugin,
 }
 
 /*
- * plugin_script_print_log: print script infos in log (usually for crash dump)
+ * Prints scripts in WeeChat log file (usually for crash dump).
  */
 
 void