From eb4fafc5041de33d68e84a88b4e092a09e688d36 Mon Sep 17 00:00:00 2001
From: Ilia Ross <ilia@ross.gdn>
Date: Sun, 3 May 2026 17:17:40 +0200
Subject: [PATCH] Add missing comments

---
 nftables/edit_rule.cgi    |  6 +++++
 nftables/import_table.cgi |  2 ++
 nftables/nftables-lib.pl  | 47 +++++++++++++++++++++++++++++++++++++++
 nftables/save_rule.cgi    |  2 ++
 4 files changed, 57 insertions(+)

diff --git a/nftables/edit_rule.cgi b/nftables/edit_rule.cgi
index f3c45e208..0b54769f5 100755
--- a/nftables/edit_rule.cgi
+++ b/nftables/edit_rule.cgi
@@ -36,6 +36,8 @@ my @addr_set_opts;
 my @port_set_opts;
 my %set_families;
 
+# split_multi_value(string)
+# Splits an nftables comma list for multi-select form values
 sub split_multi_value
 {
     my ($v) = @_;
@@ -322,6 +324,8 @@ if ($in{'new'}) {
 }
 print ui_form_end(\@buttons);
 
+# js_array(values...)
+# Returns a JavaScript array literal for simple strings
 sub js_array
 {
     my (@vals) = @_;
@@ -333,6 +337,8 @@ sub js_array
     } @vals)."]";
 }
 
+# js_object(%values)
+# Returns a JavaScript object literal for simple string pairs
 sub js_object
 {
     my (%vals) = @_;
diff --git a/nftables/import_table.cgi b/nftables/import_table.cgi
index 9acdb1fdf..78468c3ab 100755
--- a/nftables/import_table.cgi
+++ b/nftables/import_table.cgi
@@ -84,6 +84,8 @@ print ui_table_end();
 print ui_form_end([ [ undef, $text{'import_ok'} ] ]);
 ui_print_footer("active.cgi", $text{'active_return'});
 
+# unique_import_table_name(&source-table, &saved-tables, &active-tables)
+# Returns an unused table name for an imported active table
 sub unique_import_table_name
 {
 my ($source, $saved, $active_tables) = @_;
diff --git a/nftables/nftables-lib.pl b/nftables/nftables-lib.pl
index 765f91413..cda88638a 100644
--- a/nftables/nftables-lib.pl
+++ b/nftables/nftables-lib.pl
@@ -382,6 +382,8 @@ unlink_file($tmp);
 return (\@tables, undef);
 }
 
+# tokenize_nft_rule(rule-text)
+# Splits an nftables rule line into parser tokens
 sub tokenize_nft_rule
 {
 my ($line) = @_;
@@ -443,6 +445,8 @@ while ($i < $len) {
 return @tokens;
 }
 
+# unquote_nft_string(string)
+# Removes nftables-style quotes and escapes from a string token
 sub unquote_nft_string
 {
 my ($s) = @_;
@@ -458,6 +462,8 @@ elsif ($s =~ /^'(.*)'$/s) {
 return $s;
 }
 
+# escape_nft_string(string)
+# Escapes a string for use inside nftables double quotes
 sub escape_nft_string
 {
 my ($s) = @_;
@@ -467,6 +473,8 @@ $s =~ s/"/\\"/g;
 return $s;
 }
 
+# guess_addr_family(address, [fallback])
+# Returns ip or ip6 based on an address-like value
 sub guess_addr_family
 {
 my ($addr, $fallback) = @_;
@@ -475,6 +483,8 @@ return "ip6" if (defined($addr) && $addr =~ /:/);
 return "ip";
 }
 
+# validate_chain_base(type, hook, priority, policy)
+# Returns true if a chain has a complete or empty base-chain definition
 sub validate_chain_base
 {
 my ($type, $hook, $priority, $policy) = @_;
@@ -627,6 +637,8 @@ reindex_table_rules($table);
 return;
 }
 
+# move_rule_in_chain(&table, chain, index, direction)
+# Moves one rule within its chain and returns true if changed
 sub move_rule_in_chain
 {
 my ($table, $chain, $idx, $dir) = @_;
@@ -674,6 +686,8 @@ reindex_table_rules($table);
 return 1;
 }
 
+# format_addr_expr(direction, &rule)
+# Formats a source or destination address expression
 sub format_addr_expr
 {
 my ($dir, $rule) = @_;
@@ -683,6 +697,8 @@ my $fam = guess_addr_family($val, $rule->{$dir."_family"});
 return $fam." ".$dir." ".$val;
 }
 
+# format_l4proto_expr(&rule)
+# Formats a layer-4 protocol expression
 sub format_l4proto_expr
 {
 my ($rule) = @_;
@@ -695,6 +711,8 @@ if ($fam eq 'ip' || $fam eq 'ip6') {
 return "meta l4proto ".$proto;
 }
 
+# format_port_expr(direction, &rule)
+# Formats a source or destination port expression
 sub format_port_expr
 {
 my ($dir, $rule) = @_;
@@ -711,6 +729,8 @@ return if (!defined($proto) || $proto eq '');
 return $proto." ".$dir." ".$val;
 }
 
+# format_tcp_flags_expr(&rule)
+# Formats a TCP flags expression
 sub format_tcp_flags_expr
 {
 my ($rule) = @_;
@@ -722,6 +742,8 @@ if (defined($rule->{'tcp_flags_mask'}) && $rule->{'tcp_flags_mask'} ne '') {
 return "tcp flags ".$val;
 }
 
+# format_limit_expr(&rule)
+# Formats a rate limit expression
 sub format_limit_expr
 {
 my ($rule) = @_;
@@ -735,6 +757,8 @@ if (defined($rule->{'limit_burst'}) && $rule->{'limit_burst'} ne '') {
 return $out;
 }
 
+# format_log_expr(&rule)
+# Formats a log expression
 sub format_log_expr
 {
 my ($rule) = @_;
@@ -750,6 +774,8 @@ if (defined($rule->{'log_level'}) && $rule->{'log_level'} ne '') {
 return join(" ", @p);
 }
 
+# parse_rule_text(rule-text)
+# Parses one nftables rule line into structured fields where possible
 sub parse_rule_text
 {
 my ($line) = @_;
@@ -950,6 +976,8 @@ $rule{'exprs'} = \@exprs;
 return \%rule;
 }
 
+# format_rule_text(&rule)
+# Formats a structured rule hash into nftables rule text
 sub format_rule_text
 {
 my ($rule) = @_;
@@ -1179,6 +1207,8 @@ $text =~ s/\s+$//;
 return $text;
 }
 
+# parse_set_elements_string(string)
+# Parses a comma-separated nftables set elements string
 sub parse_set_elements_string
 {
 my ($text) = @_;
@@ -1191,6 +1221,8 @@ my @vals = split(/\s*,\s*/, $text);
 return \@vals;
 }
 
+# parse_set_elements_input(string)
+# Parses set elements from textarea input
 sub parse_set_elements_input
 {
 my ($text) = @_;
@@ -1203,6 +1235,8 @@ $text =~ s/\n/,/g;
 return parse_set_elements_string($text);
 }
 
+# set_elements_text(&set)
+# Returns set elements formatted for textarea editing
 sub set_elements_text
 {
 my ($set) = @_;
@@ -1211,6 +1245,8 @@ return "" if (!$set->{'elements'} || ref($set->{'elements'}) ne 'ARRAY');
 return join("\n", @{$set->{'elements'}});
 }
 
+# set_elements_summary(&set)
+# Returns a short set elements summary for table listings
 sub set_elements_summary
 {
 my ($set) = @_;
@@ -1270,6 +1306,8 @@ my ($bb) = $b =~ /^(\d+)/;
 return ($aa || 0) <=> ($bb || 0) || $a cmp $b;
 }
 
+# set_type_kind(type)
+# Returns addr, port or undef for a set type
 sub set_type_kind
 {
 my ($type) = @_;
@@ -1279,6 +1317,8 @@ return 'port' if ($type =~ /(service|port)$/);
 return;
 }
 
+# set_type_family(type)
+# Returns ip or ip6 for address set types
 sub set_type_family
 {
 my ($type) = @_;
@@ -1288,6 +1328,8 @@ return 'ip' if ($type eq 'ipv4_addr');
 return;
 }
 
+# set_name_from_value(value)
+# Returns the set name from an @set reference value
 sub set_name_from_value
 {
 my ($val) = @_;
@@ -1296,6 +1338,8 @@ return $1 if ($val =~ /^\@(\S+)$/);
 return;
 }
 
+# rule_uses_set(&rule, set-name)
+# Returns true if a rule references a set
 sub rule_uses_set
 {
 my ($rule, $setname) = @_;
@@ -1307,6 +1351,8 @@ return 1 if ($rule->{'text'} && $rule->{'text'} =~ /\@\Q$setname\E\b/);
 return 0;
 }
 
+# count_set_references(&table, set-name)
+# Returns the number of rules in a table that reference a set
 sub count_set_references
 {
 my ($table, $setname) = @_;
@@ -1724,6 +1770,7 @@ return;
 }
 
 # describe_rule(&rule)
+# Returns a human-readable rule summary for listings
 sub describe_rule
 {
 my ($r) = @_;
diff --git a/nftables/save_rule.cgi b/nftables/save_rule.cgi
index 264738515..a83a7929a 100755
--- a/nftables/save_rule.cgi
+++ b/nftables/save_rule.cgi
@@ -37,6 +37,8 @@ foreach my $check (
     }
 }
 
+# join_multi_value(string)
+# Joins multi-select form values into an nftables comma list
 sub join_multi_value
 {
     my ($v) = @_;