From f3e42874b80ebfe86e7ca7db228ec1ffa34d4445 Mon Sep 17 00:00:00 2001 From: Daniel Thayer Date: Thu, 15 Mar 2018 14:16:00 -0500 Subject: [PATCH] Improve config framework documentation comments Fixed typos and formatting. --- scripts/base/frameworks/config/README | 2 +- scripts/base/frameworks/config/main.bro | 4 +- .../base/frameworks/input/readers/config.bro | 6 +-- src/option.bif | 43 ++++++++++--------- 4 files changed, 28 insertions(+), 27 deletions(-) diff --git a/scripts/base/frameworks/config/README b/scripts/base/frameworks/config/README index 95193b49a3..3640d1e8c4 100644 --- a/scripts/base/frameworks/config/README +++ b/scripts/base/frameworks/config/README @@ -1,2 +1,2 @@ -The configuration famework provides a way to change the Bro configuration +The configuration framework provides a way to change the Bro configuration in "option" values at run-time. diff --git a/scripts/base/frameworks/config/main.bro b/scripts/base/frameworks/config/main.bro index 372bb10eb4..ffd9e764ef 100644 --- a/scripts/base/frameworks/config/main.bro +++ b/scripts/base/frameworks/config/main.bro @@ -1,6 +1,6 @@ ##! The configuration framework provides a way to change Bro options -##! (as specified by the option keyword) at runtime. It also logs runtime changes -##! to options to config.log. +##! (as specified by the "option" keyword) at runtime. It also logs runtime +##! changes to options to config.log. module Config; diff --git a/scripts/base/frameworks/input/readers/config.bro b/scripts/base/frameworks/input/readers/config.bro index 166228e81f..0d334b9b65 100644 --- a/scripts/base/frameworks/input/readers/config.bro +++ b/scripts/base/frameworks/input/readers/config.bro @@ -33,12 +33,12 @@ export { ## and also does not track removals. If you need this, combine the event ## with a table reader. ## - ## name: name of the input stream. + ## name: Name of the input stream. ## - ## source: source of the input stream. + ## source: Source of the input stream. ## ## id: ID of the configuration option being set. ## - ## value: new value of the configuration option being set. + ## value: New value of the configuration option being set. global new_value: event(name: string, source: string, id: string, value: any); } diff --git a/src/option.bif b/src/option.bif index 59f4a0fec4..011db2f069 100644 --- a/src/option.bif +++ b/src/option.bif @@ -1,6 +1,5 @@ -##! The option built-in functions allow the scripting layer to -##! change the value of option-values and to be notified when -##! option values change. +##! Definitions of built-in functions that allow the scripting layer to +##! change the value of options and to be notified when option values change. module Option; @@ -8,16 +7,16 @@ module Option; #include "NetVar.h" %%} -## Sets an option to a new value. This change will also cause the option change handlers -## to be called. +## Set an option to a new value. This change will also cause the option change +## handlers to be called. ## ## ID: The ID of the option to update. ## ## val: The new value of the option. ## -## location: optional parameter detailing where this change originated from. +## location: Optional parameter detailing where this change originated from. ## -## Returns: true on success, false when an error occured. +## Returns: true on success, false when an error occurred. ## ## .. bro:see:: Option::set_change_handler function Option::set%(ID: string, val: any, location: string &default=""%): bool @@ -74,24 +73,26 @@ function Option::set%(ID: string, val: any, location: string &default=""%): bool return new Val(1, TYPE_BOOL); %} -## Set the change handler for the option *ID*. The change handler will be called anytime -## :bro:id:`Option::set` is called fot *ID*. +## Set a change handler for an option. The change handler will be +## called anytime :bro:id:`Option::set` is called for the option. ## ## ID: The ID of the option for which change notifications are desired. ## -## on_change: The function that will be called when a change occurs. The function can choose to -## receive two or three parameters: the first parameter is a string containing *ID*, -## the second parameter is the new option value. The third, optional, parameter is the -## location string as passed to Option::set. Note that the global value is not yet changed -## when the function is called. The passed function has to return the new value that -## it wants the option to be set to. This enables it to reject changes, or change values -## that are being set. When several change handlers are set for an option they are chained; -## the second change handler will see the return value of the first change handler as the -## "new value". +## on_change: The function that will be called when a change occurs. The +## function can choose to receive two or three parameters: the first +## parameter is a string containing *ID*, the second parameter is +## the new option value. The third, optional, parameter is the +## location string as passed to Option::set. Note that the global +## value is not yet changed when the function is called. The passed +## function has to return the new value that it wants the option to +## be set to. This enables it to reject changes, or change values +## that are being set. When several change handlers are set for an +## option they are chained; the second change handler will see the +## return value of the first change handler as the "new value". ## -## priority: The priority of the function that was added; functions with higher priority are -## called first, functions with the same priority are called in the order in which -## they were added. +## priority: The priority of the function that was added; functions with higher +## priority are called first, functions with the same priority are +## called in the order in which they were added. ## ## Returns: true when the change handler was set, false when an error occurred. ##