From 5a7645fac1fd3d6fee8c81bfac5434c4f6b2694e Mon Sep 17 00:00:00 2001
From: Juliana Fajardini <jufajardini@gmail.com>
Date: Wed, 9 Feb 2022 17:26:25 +0000
Subject: [PATCH] rust: add comment tags to support documentation

With these, the portion of code within the tags should be included
in the related code-snippets (for frame support documentation) w/o
errors, even if the code within changes. The tags can also work as
a reminder that the existing code is being shown elsewhere, so folks
know documentation might need updates, in case of major changes.
---
 rust/src/sip/sip.rs       | 7 ++++++-
 rust/src/telnet/telnet.rs | 4 ++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/rust/src/sip/sip.rs b/rust/src/sip/sip.rs
index a321ca7dae..c775e6536c 100755
--- a/rust/src/sip/sip.rs
+++ b/rust/src/sip/sip.rs
@@ -26,6 +26,7 @@ use nom7::Err;
 use std;
 use std::ffi::CString;
 
+// app-layer-frame-documentation tag start: FrameType enum
 #[derive(AppLayerFrameType)]
 pub enum SIPFrameType {
     Pdu,
@@ -36,6 +37,7 @@ pub enum SIPFrameType {
     RequestBody,
     ResponseBody,
 }
+// app-layer-frame-documentation tag end: FrameType enum
 
 #[derive(AppLayerEvent)]
 pub enum SIPEvent {
@@ -107,6 +109,7 @@ impl SIPState {
         }
     }
 
+    // app-layer-frame-documentation tag start: parse_request
     fn parse_request(&mut self, flow: *const core::Flow, stream_slice: StreamSlice) -> bool {
         let input = stream_slice.as_slice();
         let _pdu = Frame::new_ts(
@@ -129,6 +132,7 @@ impl SIPState {
                 self.transactions.push(tx);
                 return true;
             }
+            // app-layer-frame-documentation tag end: parse_request
             Err(Err::Incomplete(_)) => {
                 self.set_event(SIPEvent::IncompleteData);
                 return false;
@@ -181,7 +185,7 @@ impl SIPTransaction {
     }
 }
 
-
+// app-layer-frame-documentation tag start: function to add frames
 fn sip_frames_ts(flow: *const core::Flow, stream_slice: &StreamSlice, r: &Request) {
     let oi = stream_slice.as_slice();
     let _f = Frame::new_ts(
@@ -213,6 +217,7 @@ fn sip_frames_ts(flow: *const core::Flow, stream_slice: &StreamSlice, r: &Reques
         SCLogDebug!("ts: request_body {:?}", _f);
     }
 }
+// app-layer-frame-documentation tag end: function to add frames
 
 fn sip_frames_tc(flow: *const core::Flow, stream_slice: &StreamSlice, r: &Response) {
     let oi = stream_slice.as_slice();
diff --git a/rust/src/telnet/telnet.rs b/rust/src/telnet/telnet.rs
index 494c6a12d7..bada4a3b20 100644
--- a/rust/src/telnet/telnet.rs
+++ b/rust/src/telnet/telnet.rs
@@ -141,6 +141,7 @@ impl TelnetState {
         None
     }
 
+    // app-layer-frame-documentation tag start: parse_request
     fn parse_request(
         &mut self, flow: *const Flow, stream_slice: &StreamSlice, input: &[u8],
     ) -> AppLayerResult {
@@ -191,10 +192,12 @@ impl TelnetState {
                             -1 as i64,
                             TelnetFrameType::Data as u8,
                         )
+                    // app-layer-frame-documentation tag end: parse_request
                     };
                     self.request_specific_frame = f;
                 }
             }
+            // app-layer-frame-documentation tag start: update frame_len
             match parser::parse_message(start) {
                 Ok((rem, request)) => {
                     let consumed = start.len() - rem.len();
@@ -205,6 +208,7 @@ impl TelnetState {
 
                     if let Some(frame) = &self.request_frame {
                         frame.set_len(flow, 0, consumed as i64);
+                        // app-layer-frame-documentation tag end: update frame_len
                         self.request_frame = None;
                     }
                     if let Some(frame) = &self.request_specific_frame {
-- 
2.47.2