Fix typos and formatting in event and BiF documentation

src/analyzer/protocol/dns/events.bif

@@ -367,7 +367,7 @@ event dns_MX_reply%(c: connection, msg: dns_msg, ans: dns_answer, name: string,
 ##
 ## ans: The type-independent part of the parsed answer record.
 ##
-## str: The textual information returned by the reply.
+## strs: The textual information returned by the reply.
 ##
 ## .. bro:see:: dns_AAAA_reply dns_A_reply dns_CNAME_reply dns_EDNS_addl
 ##    dns_HINFO_reply dns_MX_reply dns_NS_reply dns_PTR_reply dns_SOA_reply
@@ -392,6 +392,8 @@ event dns_TXT_reply%(c: connection, msg: dns_msg, ans: dns_answer, strs: string_
 ##
 ## ans: The type-independent part of the parsed answer record.
 ##
+## target: TODO
+##
 ## priority: Priority of the SRV response.
 ##
 ## weight: Weight of the SRV response.
@@ -408,8 +410,7 @@ event dns_TXT_reply%(c: connection, msg: dns_msg, ans: dns_answer, strs: string_
 event dns_SRV_reply%(c: connection, msg: dns_msg, ans: dns_answer, target: string, priority: count, weight: count, p: count%);
 
 ## Generated on DNS reply resource records when the type of record is not one
-## that Bro knows how to parse and generate another more specific specific
+## that Bro knows how to parse and generate another more specific event.
-## event.
 ##
 ## c: The connection, which may be UDP or TCP depending on the type of the
 ##    transport-layer session being analyzed.

src/analyzer/protocol/pop3/events.bif

@@ -105,8 +105,8 @@ event pop3_unexpected%(c: connection, is_orig: bool,
 ##
 ## c: The connection.
 ##
-## .. bro:see:: pop3_data pop3_login_failure pop3_login_success pop3_reply pop3_request
+## .. bro:see:: pop3_data pop3_login_failure pop3_login_success pop3_reply
-##    pop3_unexpected
+##    pop3_request pop3_unexpected
 ##
 ## .. todo:: Bro's current default configuration does not activate the protocol
 ##    analyzer that generates this event; the corresponding script has not yet

src/analyzer/protocol/radius/events.bif

@@ -3,10 +3,9 @@
 ## See `Wikipedia <http://en.wikipedia.org/wiki/RADIUS>`__ for more
 ## information about RADIUS.
 ##
-## c: The connection
+## c: The connection.
-## msg_type: The value of the code field (1 == Access-Request, 2 == Access-Accept, etc.)
+##
-## trans_id: The RADIUS transaction identifier
+## result: TODO
-## authenticator: The value of the authenticator field
 ##
 event radius_message%(c: connection, result: RADIUS::Message%);
 
@@ -15,9 +14,11 @@ event radius_message%(c: connection, result: RADIUS::Message%);
 ## See `Wikipedia <http://en.wikipedia.org/wiki/RADIUS>`__ for more
 ## information about RADIUS.
 ##
-## c: The connection
+## c: The connection.
-## attr_type: The value of the code field (1 == User-Name, 2 == User-Password, etc.)
+##
-## authenticator: The value of the authenticator field
+## attr_type: The value of the code field (1 == User-Name, 2 == User-Password, etc.).
+##
+## value: TODO
 ##
 event radius_attribute%(c: connection, attr_type: count, value: string%);
 

src/analyzer/protocol/smtp/events.bif

@@ -99,10 +99,10 @@ event smtp_data%(c: connection, is_orig: bool, data: string%);
 ## .. bro:see:: smtp_data  smtp_request smtp_reply
 event smtp_unexpected%(c: connection, is_orig: bool, msg: string, detail: string%);
 
-## Generated if a connection switched to using TLS using STARTTLS. After this event
+## Generated if a connection switched to using TLS using STARTTLS. After this
-## no more SMTP events will be raised for the connection. See the SSL analyzer for
+## event no more SMTP events will be raised for the connection. See the SSL
-## related SSL events, which will now be generated.
+## analyzer for related SSL events, which will now be generated.
 ##
-## c: The connection
+## c: The connection.
 ##
 event smtp_starttls%(c: connection%);

src/analyzer/protocol/ssl/events.bif

@@ -86,8 +86,8 @@ event ssl_server_hello%(c: connection, version: count, possible_ts: time, server
 event ssl_extension%(c: connection, is_orig: bool, code: count, val: string%);
 
 ## Generated for an SSL/TLS Elliptic Curves extension. This TLS extension is
-## defined in :rfc:`4492` and sent by the client in the initial handshake. It gives
+## defined in :rfc:`4492` and sent by the client in the initial handshake. It
-## the list of elliptic curves supported by the client.
+## gives the list of elliptic curves supported by the client.
 ##
 ## c: The connection.
 ##
@@ -118,13 +118,13 @@ event ssl_extension_elliptic_curves%(c: connection, is_orig: bool, curves: index
 ##    ssl_extension_server_name ssl_server_curve
 event ssl_extension_ec_point_formats%(c: connection, is_orig: bool, point_formats: index_vec%);
 
-## Generated if a named curve is chosen by the server for an SSL/TLS connection. The
+## Generated if a named curve is chosen by the server for an SSL/TLS connection.
-## curve is sent by the server in the ServerKeyExchange message as defined in
+## The curve is sent by the server in the ServerKeyExchange message as defined
-## :rfc:`4492`, in case an ECDH or ECDHE cipher suite is chosen.
+## in :rfc:`4492`, in case an ECDH or ECDHE cipher suite is chosen.
 ##
 ## c: The connection.
 ##
-## point_formats: List of supported point formats.
+## curve: The curve.
 ##
 ## .. bro:see:: ssl_alert ssl_client_hello ssl_established ssl_server_hello
 ##    ssl_session_ticket_handshake ssl_extension
@@ -151,7 +151,7 @@ event ssl_dh_server_params%(c: connection, p: string, q: string, Ys: string%);
 ## Generated for an SSL/TLS Application-Layer Protocol Negotiation extension.
 ## This TLS extension is defined in draft-ietf-tls-applayerprotoneg and sent in
 ## the initial handshake. It contains the list of client supported application
-## protocols by the client or the server, respectovely.
+## protocols by the client or the server, respectively.
 ##
 ## At the moment it is mostly used to negotiate the use of SPDY / HTTP2-drafts.
 ##
@@ -169,15 +169,15 @@ event ssl_extension_application_layer_protocol_negotiation%(c: connection, is_or
 
 ## Generated for an SSL/TLS Server Name extension. This SSL/TLS extension is
 ## defined in :rfc:`3546` and sent by the client in the initial handshake. It
-## contains the name of the server it is contacting. This information can be used
+## contains the name of the server it is contacting. This information can be
-## by the server to choose the correct certificate for the host the client wants to
+## used by the server to choose the correct certificate for the host the client
-## contact.
+## wants to contact.
 ##
 ## c: The connection.
 ##
 ## is_orig: True if event is raised for originator side of the connection.
 ##
-## protocols: List of supported application layer protocols.
+## names: Name of server.
 ##
 ## .. bro:see:: ssl_alert ssl_client_hello ssl_established ssl_server_hello
 ##    ssl_session_ticket_handshake ssl_extension
@@ -244,9 +244,9 @@ event ssl_alert%(c: connection, is_orig: bool, level: count, desc: count%);
 ##    ssl_alert
 event ssl_session_ticket_handshake%(c: connection, ticket_lifetime_hint: count, ticket: string%);
 
-## Generated for SSL/TLS heartbeat messages that are sent before session encryption
+## Generated for SSL/TLS heartbeat messages that are sent before session
-## starts. Generally heartbeat messages should rarely be seen in normal TLS traffic.
+## encryption starts. Generally heartbeat messages should rarely be seen in
-## Heartbeats are described in :rfc:`6520`.
+## normal TLS traffic. Heartbeats are described in :rfc:`6520`.
 ##
 ## c: The connection.
 ##
@@ -254,12 +254,13 @@ event ssl_session_ticket_handshake%(c: connection, ticket_lifetime_hint: count,
 ##
 ## length: length of the entire heartbeat message.
 ##
-## heartbeat_type: type of the heartbeat message. Per RFC, 1 = request, 2 = response
+## heartbeat_type: type of the heartbeat message. Per RFC, 1 = request, 2 = response.
 ##
-## payload_length: length of the payload of the heartbeat message, according to packet field
+## payload_length: length of the payload of the heartbeat message, according to
+##                 packet field.
 ##
-## payload: payload contained in the heartbeat message. Size can differ from payload_length,
+## payload: payload contained in the heartbeat message. Size can differ from
-##          if payload_length and actual packet length disagree.
+##          payload_length, if payload_length and actual packet length disagree.
 ##
 ## .. bro:see::  ssl_client_hello ssl_established ssl_extension ssl_server_hello
 ##    ssl_alert ssl_encrypted_data
@@ -269,13 +270,13 @@ event ssl_heartbeat%(c: connection, is_orig: bool, length: count, heartbeat_type
 ## started.
 ##
 ## Note that :bro:id:`SSL::disable_analyzer_after_detection` has to be changed
-## from its default to false for this this event to be generated.  
+## from its default to false for this event to be generated.  
 ##
 ## c: The connection.
 ##
 ## is_orig: True if event is raised for originator side of the connection.
 ##
-## content type: message type as reported by TLS session layer
+## content_type: message type as reported by TLS session layer.
 ##
 ## length: length of the entire heartbeat message.
 ##
@@ -284,8 +285,8 @@ event ssl_heartbeat%(c: connection, is_orig: bool, length: count, heartbeat_type
 event ssl_encrypted_data%(c: connection, is_orig: bool, content_type: count, length: count%);
 
 ## This event contains the OCSP response contained in a Certificate Status Request
-## message, when the client requested OCSP stapling and the server supports it. See
+## message, when the client requested OCSP stapling and the server supports it.
-## description in :rfc:`6066`
+## See description in :rfc:`6066`.
 ##
 ## c: The connection.
 ##

src/event.bif

@@ -360,9 +360,9 @@ event content_gap%(c: connection, is_orig: bool, seq: count, length: count%);
 ##
 ## .. note::
 ##
-##    Bro comes with a script :doc:`/scripts/policy/misc/capture-loss.bro` that uses
+##    Bro comes with a script :doc:`/scripts/policy/misc/capture-loss.bro` that
-##    this event to estimate packet loss and report when a predefined threshold
+##    uses this event to estimate packet loss and report when a predefined
-##    is exceeded.
+##    threshold is exceeded.
 event gap_report%(dt: interval, info: gap_info%);
 
 ## Generated when a protocol analyzer confirms that a connection is indeed
@@ -1011,8 +1011,8 @@ event dns_mapping_lost_name%(dm: dns_mapping%);
 ##    dns_mapping_valid
 event dns_mapping_altered%(dm: dns_mapping, old_addrs: addr_set, new_addrs: addr_set%);
 
-## A meta event generated for events that Bro raises. This will report all events
+## A meta event generated for events that Bro raises. This will report all
-## for which at least one handler is defined.
+## events for which at least one handler is defined.
 ##
 ## Note that handling this meta event is expensive and should be limited to
 ## debugging purposes.

src/file_analysis/analyzer/x509/events.bif

@@ -43,9 +43,9 @@ event x509_extension%(f: fa_file, ext: X509::Extension%);
 event x509_ext_basic_constraints%(f: fa_file, ext: X509::BasicConstraints%);
 
 ## Generated for the X509 subject alternative name extension seen in a certificate.
-## This extension can be used to allow additional entities to be bound to the subject
+## This extension can be used to allow additional entities to be bound to the
-## of the certificate. Usually it is used to specify one or multiple DNS names for 
+## subject of the certificate. Usually it is used to specify one or multiple DNS
-## which a certificate is valid.
+## names for which a certificate is valid.
 ##
 ## f: The file.
 ##

src/file_analysis/analyzer/x509/functions.bif

@@ -106,9 +106,9 @@ STACK_OF(X509)* x509_get_untrusted_stack(VectorVal* certs_vec)
 
 ## Parses a certificate into an X509::Certificate structure.
 ##
-## cert: The X509 certificicate opaque handle
+## cert: The X509 certificate opaque handle.
 ##
-## Returns: A X509::Certificate structure
+## Returns: A X509::Certificate structure.
 ##
 ## .. bro:see:: x509_certificate x509_extension x509_ext_basic_constraints
 ##              x509_ext_subject_alternative_name x509_verify
@@ -123,13 +123,13 @@ function x509_parse%(cert: opaque of x509%): X509::Certificate
 
 ## Returns the string form of a certificate.
 ##
-## cert: The X509 certificate opaque handle
+## cert: The X509 certificate opaque handle.
 ##
 ## pem: A boolean that specifies if the certificate is returned
 ##      in pem-form (true), or as the raw ASN1 encoded binary
 ##      (false).
 ##
-## Returns: X509 certificate as a string
+## Returns: X509 certificate as a string.
 ##
 ## .. bro:see:: x509_certificate x509_extension x509_ext_basic_constraints
 ##              x509_ext_subject_alternative_name x509_parse x509_verify
@@ -158,14 +158,14 @@ function x509_get_certificate_string%(cert: opaque of x509, pem: bool &default=F
 ##
 ## certs: Specifies the certificate chain to use. Server certificate first.
 ##
-## ocsp_reply: the ocsp reply to validate
+## ocsp_reply: the ocsp reply to validate.
 ##
-## root_certs: A list of root certificates to validate the certificate chain
+## root_certs: A list of root certificates to validate the certificate chain.
 ##
 ## verify_time: Time for the validity check of the certificates.
 ##
-## Returns: A record of type X509::Result containing the result code of the verify
+## Returns: A record of type X509::Result containing the result code of the
-##          operation.
+##          verify operation.
 ##
 ## .. bro:see:: x509_certificate x509_extension x509_ext_basic_constraints
 ##              x509_ext_subject_alternative_name x509_parse
@@ -377,12 +377,13 @@ x509_ocsp_cleanup:
 ##        the given certificate against the root store given in *root_certs*.
 ##        The host certificate has to be at index 0.
 ##
-## root_certs: A list of root certificates to validate the certificate chain
+## root_certs: A list of root certificates to validate the certificate chain.
 ##
 ## verify_time: Time for the validity check of the certificates.
 ##
-## Returns: A record of type X509::Result containing the result code of the verify
+## Returns: A record of type X509::Result containing the result code of the
-##          operation. In case of success also returns the full certificate chain.
+##          verify operation. In case of success also returns the full
+##          certificate chain.
 ##
 ## .. bro:see:: x509_certificate x509_extension x509_ext_basic_constraints
 ##              x509_ext_subject_alternative_name x509_parse