rust/doc: add docstring to rust module files.

Issue: #4584

rust/src/applayer.rs

@@ -15,7 +15,7 @@
  * 02110-1301, USA.
  */
 
-//! Parser registration functions and common interface
+//! Parser registration functions and common interface module.
 
 use std;
 use crate::core::{self,DetectEngineState,Flow,AppLayerEventType,AppProto,Direction};

rust/src/applayertemplate/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Application layer template parser and logger module.
+
 mod parser;
 pub mod template;
 /* TEMPLATE_START_REMOVE */

rust/src/asn1/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! ASN.1 parser module.
+
 use der_parser::ber::{parse_ber_recursive, BerObject, BerObjectContent, Tag};
 use nom7::Err;
 use std::convert::TryFrom;

rust/src/bittorrent_dht/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! BitTorrent DHT application layer, logger and parser module.
+
 pub mod bittorrent_dht;
 pub mod logger;
 pub mod parser;

rust/src/common.rs

@@ -1,3 +1,5 @@
+//! Utility library module for commonly used strings, hexadecimals and other elements.
+
 use super::build_slice;
 use crate::jsonbuilder::HEX;
 use std::ffi::CString;

rust/src/conf.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module for retrieving configuration details.
+
 use std::os::raw::c_char;
 use std::os::raw::c_void;
 use std::os::raw::c_int;

rust/src/core.rs

@@ -15,7 +15,7 @@
  * 02110-1301, USA.
  */
 
-// This file exposes items from the core "C" code to Rust.
+//! This module exposes items from the core "C" code to Rust.
 
 use std;
 use crate::filecontainer::*;

rust/src/dcerpc/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! DCE/RPC protocol parser, logger and detection module.
+
 pub mod dcerpc;
 pub mod dcerpc_udp;
 pub mod parser;

rust/src/detect/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module for rule parsing.
+
 pub mod byte_math;
 pub mod error;
 pub mod iprep;

rust/src/dhcp/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! DHCP parser, detection and logger module.
+
 pub mod dhcp;
 pub mod parser;
 pub mod logger;

rust/src/dns/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! DNS parser, detection, logger and application layer module.
+
 pub mod detect;
 pub mod dns;
 pub mod log;

rust/src/ffi/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module that exposes C bindings to the Suricata Rust library.
+
 pub mod hashing;
 pub mod base64;
 pub mod strings;

rust/src/filecontainer.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! This module handles file container operations (open, append, close).
+
 use std::ptr;
 use std::os::raw::{c_void};
 

rust/src/filetracker.rs

@@ -15,18 +15,17 @@
  * 02110-1301, USA.
  */
 
-/**
+//! Gap handling and Chunk-based file transfer tracker module.
- *  \file
+//!
- *  \author Victor Julien <victor@inliniac.net>
+//! GAP handling. If a data gap is encountered, the file is truncated
- *
+//! and new data is no longer pushed down to the lower level APIs.
- * Tracks chunk based file transfers. Chunks may be transferred out
+//! The tracker does continue to follow the file
- * of order, but cannot be transferred in parallel. So only one
+//
- * chunk at a time.
+//! Tracks chunk based file transfers. Chunks may be transferred out
- *
+//! of order, but cannot be transferred in parallel. So only one
- * GAP handling. If a data gap is encountered, the file is truncated
+//! chunk at a time.
- * and new data is no longer pushed down to the lower level APIs.
+//!
- * The tracker does continue to follow the file.
+//! Author: Victor Julien <victor@inliniac.net>
- */
 
 use crate::core::*;
 use std::collections::HashMap;

rust/src/frames.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module for bindings to the Suricata C frame API.
+
 use crate::applayer::StreamSlice;
 use crate::core::Flow;
 #[cfg(not(test))]

rust/src/ftp/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! FTP parser and application layer module.
+
 use nom7::bytes::complete::{tag, take_until};
 use nom7::character::complete::{digit1, multispace0};
 use nom7::combinator::{complete, map_res, opt, verify};

rust/src/http2/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! HTTP/2 parser, detection, logger and application layer module.
+
 #![allow(clippy::result_unit_err)]
 
 mod decompression;

rust/src/ike/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! IKE parser, detection, logger and application layer module.
+
 // written by Pierre Chifflier  <chifflier@wzdftpd.net>
 
 extern crate ipsec_parser;

rust/src/jsonbuilder.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+ //! Module for building JSON documents.
+
 #![allow(clippy::missing_safety_doc)]
 
 use std::cmp::max;

rust/src/kerberos.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Kerberos parser wrapper module.
+
 use nom7::IResult;
 use nom7::error::{ErrorKind, ParseError};
 use nom7::number::streaming::le_u16;

rust/src/krb/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Kerberos-v5 application layer, logger and detection module.
+
 // written by Pierre Chifflier  <chifflier@wzdftpd.net>
 
 pub mod krb5;

rust/src/lib.rs

@@ -15,6 +15,11 @@
  * 02110-1301, USA.
  */
 
+//! Suricata is a network intrusion prevention and monitoring engine.
+//!
+//! Suricata is a hybrid C and Rust application. What is found here are
+//! the components written in Rust.
+
 #![cfg_attr(feature = "strict", deny(warnings))]
 
 // Allow these patterns as its a style we like.

rust/src/log.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Logging utility module.
+
 use std;
 use std::ffi::CString;
 use std::path::Path;

rust/src/lua.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Lua wrapper module.
+
 use std::os::raw::c_char;
 use std::os::raw::c_int;
 use std::os::raw::c_long;

rust/src/lzma.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! lzma decompression utility module.
+
 use lzma_rs::decompress::{Options, Stream};
 use lzma_rs::error::Error;
 use std::io::{Cursor, Write};

rust/src/mime/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! MIME protocol parser module.
+
 use crate::common::nom7::take_until_and_consume;
 use nom7::branch::alt;
 use nom7::bytes::streaming::{tag, take_until, take_while};

rust/src/modbus/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Modbus application layer, logger, parser and detection module.
+
 pub mod detect;
 pub mod log;
 pub mod modbus;

rust/src/mqtt/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! MQTT application layer, detection, logger and parser module.
+
 pub mod detect;
 pub mod logger;
 pub mod mqtt;

rust/src/nfs/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! NFS application layer, parser, logger module.
+
 pub mod types;
 pub mod rpc_records;
 pub mod nfs_records;

rust/src/ntp/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! NTP application layer and parser module.
+
 // written by Pierre Chifflier  <chifflier@wzdftpd.net>
 
 pub mod ntp;

rust/src/pgsql/mod.rs

@@ -15,7 +15,7 @@
  * 02110-1301, USA.
  */
 
-//! PostgreSQL parser and application layer
+//! PostgreSQL parser, logger and application layer module.
 //!
 //! written by Juliana Fajardini <jufajardini@oisf.net>
 

rust/src/plugin.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Plugin utility module.
+
 pub fn init() {
     unsafe {
         let context = super::core::SCGetContext();

rust/src/quic/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! QUIC application layer, parser, detection and logger module.
+
 mod crypto;
 mod cyu;
 pub mod detect;

rust/src/rdp/mod.rs

@@ -15,7 +15,7 @@
  * 02110-1301, USA.
  */
 
-//! RDP parser and application layer
+//! RDP parser, logger and application layer module.
 //!
 //! written by Zach Kelly <zach.kelly@lmco.com>
 

rust/src/rfb/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! RFB protocol parser, logger and detection module.
+
 // Author: Frank Honza <frank.honza@dcso.de>
 
 pub mod detect;

rust/src/sip/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! SIP protocol parser, detection and logger module.
+
 // written by Giuseppe Longo <giuseppe@glongo.it>
 
 pub mod detect;

rust/src/smb/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! SMB application layer, detection, logger and parser module.
+
 pub mod error;
 pub mod smb_records;
 pub mod smb_status;

rust/src/snmp/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! SNMP application layer, parser, detection and logger module.
+
 // written by Pierre Chifflier  <chifflier@wzdftpd.net>
 
 extern crate snmp_parser;

rust/src/ssh/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! SSH application layer, logger, detection and parser module.
+
 pub mod detect;
 pub mod logger;
 mod parser;

rust/src/telnet/mod.rs

@@ -15,5 +15,7 @@
  * 02110-1301, USA.
  */
 
+//! Telnet application layer and parser module.
+
 pub mod telnet;
 mod parser;

rust/src/tftp/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! TFTP parser, logger and application layer module.
+
 // written by Clément Galland <clement.galland@epita.fr>
 
 pub mod tftp;

rust/src/util.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Utility module.
+
 use std::ffi::CStr;
 use std::os::raw::c_char;
 

rust/src/x509/mod.rs

@@ -15,6 +15,8 @@
  * 02110-1301, USA.
  */
 
+//! Module for SSL/TLS X.509 certificates parser and decoder.
+
 // written by Pierre Chifflier  <chifflier@wzdftpd.net>
 
 use crate::common::rust_string_to_c;