[PATCH v3 04/13] devtools: handle multiple drivers in doc check

[David Marchand <david.marchand@redhat.com>]

Some drivers have multiple doc files sharing one code directory
(e.g., igb, igc, e1000 variants). Others have doc files for VF/DCF
variants (e.g., ice_dcf, ixgbe_vf).

Extend driver_code_dir() to strip variant suffixes and map driver
names to their shared code directories.

Build a cache mapping each code directory to its associated doc
files. Add docs_for_code() to retrieve all doc names for a given
code directory.

Add items_not_in() to compute set difference between two lists.
Use it in check_rte_flow() to compare doc vs code items:
- items documented but not in code are always reported,
- items in code but not documented in any doc for the code
  directory are reported, avoiding false positives when multiple
  docs share the same code.

Also rename doc files to match their code directory names.

Signed-off-by: David Marchand <david.marchand@redhat.com>
---
Changes since v2:
- introduced logic earlier in the series,
- added comments and implemented for rte_flow checks,

---
 MAINTAINERS                                   |   2 +-
 devtools/check-doc-vs-code.sh                 | 109 +++++++++++++++---
 .../features/{afpacket.ini => af_packet.ini}  |   2 +-
 .../features/{cxgbevf.ini => cxgbe_vf.ini}    |   2 +-
 4 files changed, 98 insertions(+), 17 deletions(-)
 rename doc/guides/nics/features/{afpacket.ini => af_packet.ini} (70%)
 rename doc/guides/nics/features/{cxgbevf.ini => cxgbe_vf.ini} (90%)

diff --git a/MAINTAINERS b/MAINTAINERS
index 1720cff62e..e05bea2f0c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -679,7 +679,7 @@ F: examples/bond/
 Linux AF_PACKET
 M: Stephen Hemminger <stephen@networkplumber.org>
 F: drivers/net/af_packet/
-F: doc/guides/nics/features/afpacket.ini
+F: doc/guides/nics/features/af_packet.ini
 F: app/test/test_pmd_af_packet.c
 
 Linux AF_XDP
diff --git a/devtools/check-doc-vs-code.sh b/devtools/check-doc-vs-code.sh
index e141fe9938..7afc18d153 100755
--- a/devtools/check-doc-vs-code.sh
+++ b/devtools/check-doc-vs-code.sh
@@ -36,35 +36,86 @@ has_file_change() # <pattern>
 	changed_files | grep -q "$1"
 }
 
+net_driver_from_path() # <path>
+{
+	sed -rn '
+		s,.*drivers/net/intel/([^/]*)/.*,\1,p; t
+		s,.*drivers/net/([^./]*)/.*,\1,p; t
+		s,.*doc/guides/nics/features/([^./]*).*,\1,p' |
+	grep -v '^default$'
+}
+
 changed_net_drivers()
 {
 	[ -n "$drivers" ] ||
 		drivers=$(changed_files |
-			sed -rn '
-				s,^drivers/net/intel/([^/]*).*,\1,p; t
-				s,^drivers/net/([^/]*).*,\1,p; t
-				s,^doc/guides/nics/features/([^.]*).*,\1,p' |
+			net_driver_from_path |
 			sort -u)
 	echo "$drivers"
 }
 
 all_net_drivers()
 {
-	find $rootdir/drivers/net -name meson.build |
-	sed -rn '
-		s,.*drivers/net/intel/([^/]*).*,\1,p; t
-		s,.*drivers/net/([^/]*).*,\1,p' |
+	{
+		find $rootdir/drivers/net -name meson.build
+		ls $rootdir/doc/guides/nics/features/*.ini
+	} |
+	net_driver_from_path |
 	sort -u
 }
 
 # give back a driver directory for a doc/driver name
 driver_code_dir() # <driver_name>
 {
-	if [ -d $rootdir/drivers/net/intel/$1 ]; then
-		echo "$rootdir/drivers/net/intel/$1"
-	else
-		echo "$rootdir/drivers/net/$1"
-	fi
+	drv=$(echo "$1" | sed -r 's/_(dcf|vec|vf)$//')
+	case $drv in
+	enetc|enetc4)
+		echo "$rootdir/drivers/net/enetc" ;;
+	igb|igc|e1000)
+		echo "$rootdir/drivers/net/intel/e1000" ;;
+	*)
+		if [ -d $rootdir/drivers/net/intel/$drv ]; then
+			echo "$rootdir/drivers/net/intel/$drv"
+		else
+			echo "$rootdir/drivers/net/$drv"
+		fi ;;
+	esac
+}
+
+# create a cache of the mapping between a driver code directory and associated driver docs
+# format of this cache is:
+# ^,$drv1_directory: $drv1_doc_name1 $drv1_doc_name2,$drv2_directory: $drv2_doc_name1,...,$
+doc_code_map=","
+for d in $rootdir/doc/guides/nics/features/*.ini; do
+	drv=$(basename "$d" .ini)
+	[ "$drv" != 'default' ] || continue
+	code=$(driver_code_dir $drv)
+	case $doc_code_map in
+	*,$code:*)
+		before=${doc_code_map%,$code:*}
+		after=${doc_code_map#*,$code:}
+		drvs=${after%%,*}
+		rest=${after#*,}
+		doc_code_map="$before,$code:$drvs $drv,$rest" ;;
+	*)
+		doc_code_map="$doc_code_map$code: $drv," ;;
+	esac
+done
+
+# extract all doc names from the cache created above
+docs_for_code() # <code_dir>
+{
+	tmp=${doc_code_map#*,$1:}
+	echo ${tmp%%,*}
+}
+
+# output items from first list that are not in second list
+items_not_in() # <list1> <list2>
+{
+	{
+		[ -n "$1" ] && echo "$1"
+		[ -n "$2" ] && { echo "$2"; echo "$2"; }
+	} | sort | uniq -u
 }
 
 check_rte_flow() # <driver>
@@ -73,7 +124,37 @@ check_rte_flow() # <driver>
 	doc=$rootdir/doc/guides/nics/features/$1.ini
 	[ -d $code ] || return 0
 	[ -f $doc ] || return 0
-	report=$($selfdir/parse-flow-support.sh $code $doc)
+	code_support=$($selfdir/parse-flow-support.sh $code)
+	report=$(
+		for category in item action; do
+			section="rte_flow ${category}s]"
+			code_items=$(echo "$code_support" | sed -n "/$section/,/]/p" |
+				sed '/]/d' |        # ignore section title
+				sed 's, *=.*,,' |   # keep only item name
+				sed '/^$/d' |       # remove empty lines
+				sort -u)
+			doc_items=$(sed -n "/$section/,/]/p" "$doc" |
+				sed '/]/d' |        # ignore section title
+				sed 's, *=.*,,' |   # keep only item name
+				sed '/^$/d' |       # remove empty lines
+				sort -u)
+			{
+				# items documented but not in code
+				items_not_in "$doc_items" "$code_items"
+				# items in code but not documented in any doc for the code directory
+				all_doc_items=$(
+					for drv in $(docs_for_code $code); do
+						d=$rootdir/doc/guides/nics/features/$drv.ini
+						sed -n "/$section/,/]/p" "$d" |
+							sed '/]/d' |        # ignore section title
+							sed 's, *=.*,,' |   # keep only item name
+							sed '/^$/d'         # remove empty lines
+					done | sort -u
+				)
+				items_not_in "$code_items" "$all_doc_items"
+			} | sed "s,^,$category ,"   # prefix with category name
+		done
+	)
 	if [ -n "$report" ]; then
 		error "rte_flow doc out of sync for $1"
 		echo "$report" | sed 's,^,\t,'
diff --git a/doc/guides/nics/features/afpacket.ini b/doc/guides/nics/features/af_packet.ini
similarity index 70%
rename from doc/guides/nics/features/afpacket.ini
rename to doc/guides/nics/features/af_packet.ini
index bc669dfb8a..b1cbc54aca 100644
--- a/doc/guides/nics/features/afpacket.ini
+++ b/doc/guides/nics/features/af_packet.ini
@@ -1,5 +1,5 @@
 ;
-; Supported features of the 'afpacket' network poll mode driver.
+; Supported features of the 'af_packet' network poll mode driver.
 ;
 ; Refer to default.ini for the full list of available PMD features.
 ;
diff --git a/doc/guides/nics/features/cxgbevf.ini b/doc/guides/nics/features/cxgbe_vf.ini
similarity index 90%
rename from doc/guides/nics/features/cxgbevf.ini
rename to doc/guides/nics/features/cxgbe_vf.ini
index a921cda6b1..b77b202272 100644
--- a/doc/guides/nics/features/cxgbevf.ini
+++ b/doc/guides/nics/features/cxgbe_vf.ini
@@ -1,5 +1,5 @@
 ;
-; Supported features of the 'cxgbevf' network poll mode driver.
+; Supported features of the 'cxgbe_vf' network poll mode driver.
 ;
 ; Refer to default.ini for the full list of available PMD features.
 ;
-- 
2.54.0