#! /usr/bin/perl
# kerndoc-search.pl
# list or "--count" kernel-doc short description lines from source file(s);
# Randy Dunlap <rdunlap@xenotime.net>, 2007-04-11

my $opt_count = 0;
my $opt_format = 0;

if ($#ARGV >= 0) {
	if ($ARGV[0] eq "--help") {
		printf STDERR "kerndoc-search.pl [--count] [--format] file(s)\n";
		exit 1;
	}
	if ($ARGV[0] eq "--count") {
		shift;
		$opt_count = 1;
	}
	if ($ARGV[0] eq "--format") {
		shift;
		$opt_format = 1;
	}
}

foreach my $file (@ARGV) {
	open (FILE, $file) || die "Cannot open $file: $!\n";

	my $kerndoc_count = 0;		# tally if ($opt_count)
	my $save_shortdesc = 0;
	my $shortdesc = "";

LINE:
	while ($line = <FILE>) {	# read lines from FILE
		chomp $line;
		###printf "deb: line:$line\n";
		next LINE if ($line =~ /\*\*\*\*\*/);

		if ($line =~ /^\s*\/\*\*/) {
			$save_shortdesc = 1;
			next LINE;
		}

		if ($save_shortdesc) {
			$save_shortdesc = 0;
			# but this can easily be a false positive, so check $line:
			next LINE if ($line =~ /^\s*\*\s*$/); # mostly empty
			next LINE if ($line =~ /^\s*\*\*/); # double-*
			next LINE if ($line =~ /^\s*\*\s*DOC:/); # skip DOC:
			next LINE unless ($line =~ /^\s*\*\s*/); # must be *-line
			next LINE unless ($line =~ /:/) || ($line =~ /-/);

			$shortdesc = $line;
			$kerndoc_count++;

			if (!$opt_format) {
				printf "$line\n" unless $opt_count;
			} else {
				# print $function : $filename
				my $func;
				if ($line =~ /\s*\*\s*(.*)\s*[-:]/) {
					$func = $1;
					$func =~ s/\s*$//; # drop trailing spaces
					$func =~ s/\(\s*\)//; # drop "()"s
					# $func may contain some of the function
					# short description :( due to greedy
					# pattern matching, so eliminate it
					$func =~ s/-\s*.*$//;
					$func =~ s/\s*$//; # drop trailing spaces
				} else {
					$func = $line;
				}
				print "$func : $file:$.\n";
			}
		}
	} # end while $line

	close FILE;
	if ($opt_count) {
		printf "file $file: $kerndoc_count kernel-doc blocks\n";
	}
	else {
		if ($kerndoc_count && !$opt_format) { # when printing line contents
			printf "----- file: $file (above) -----\n";
		}
	}
} # end foreach $file
# end;