Commit 3a025e1d authored by Matthew Wilcox's avatar Matthew Wilcox Committed by Jonathan Corbet
Browse files

Add optional check for bad kernel-doc comments 



Implement a '-none' output mode for kernel-doc which will only output
warning messages, and suppresses the warning message about there being
no kernel-doc in the file.

If the build has requested additional warnings, automatically check all
.c files.  This patch does not check .h files.  Enabling the warning
by default would add about 1300 warnings, so it's default off for now.
People who care can use this to check they didn't break the docs and
maybe we'll get all the warnings fixed and be able to enable this check
by default in the future.

Signed-off-by: default avatarMatthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent e7e61fc0

scripts/Makefile.build

+5 −0
Original line number Diff line number Diff line
@@ -108,6 +108,10 @@ ifneq ($(KBUILD_CHECKSRC),0) 
  endif

endif



ifneq ($(KBUILD_ENABLE_EXTRA_GCC_CHECKS),)

  cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $< ;

endif



# Do section mismatch analysis for each module/built-in.o

ifdef CONFIG_DEBUG_SECTION_MISMATCH

  cmd_secanalysis = ; scripts/mod/modpost $@
@@ -289,6 +293,7 @@ define rule_cc_o_c 
	$(call echo-cmd,checksrc) $(cmd_checksrc)			  \

	$(call cmd_and_fixdep,cc_o_c)					  \

	$(cmd_modversions_c)						  \

	$(cmd_checkdoc)							  \

	$(call echo-cmd,objtool) $(cmd_objtool)				  \

	$(call echo-cmd,record_mcount) $(cmd_record_mcount)

endef

scripts/kernel-doc

+24 −1
Original line number Diff line number Diff line
@@ -58,6 +58,7 @@ Output format selection (mutually exclusive): 
  -man			Output troff manual page format. This is the default.

  -rst			Output reStructuredText format.

  -text			Output plain text format.

  -none			Do not output documentation, only warnings.



Output selection (mutually exclusive):

  -export		Only output documentation for symbols that have been
@@ -532,6 +533,8 @@ while ($ARGV[0] =~ m/^-(.*)/) { 
	$output_mode = "gnome";

	@highlights = @highlights_gnome;

	$blankline = $blankline_gnome;

    } elsif ($cmd eq "-none") {

	$output_mode = "none";

    } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document

	$modulename = shift @ARGV;

    } elsif ($cmd eq "-function") { # to only output specific functions
@@ -2117,6 +2120,24 @@ sub output_blockhead_list(%) { 
    }

}





## none mode output functions



sub output_function_none(%) {

}



sub output_enum_none(%) {

}



sub output_typedef_none(%) {

}



sub output_struct_none(%) {

}



sub output_blockhead_none(%) {

}



##

# generic output function for all types (function, struct/union, typedef, enum);

# calls the generated, variable output_ function name based on
@@ -3145,7 +3166,9 @@ sub process_file($) { 
	}

    }

    if ($initial_section_counter == $section_counter) {

	if ($output_mode ne "none") {

	    print STDERR "${file}:1: warning: no structured comments found\n";

	}

	if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {

	    print STDERR "    Was looking for '$_'.\n" for keys %function_table;

	}

CRA Git | Maintained and supported by SUSTech CRA and CCSE