kernel-doc overly verbose with V=0

[Jacob Keller]

Hi,

I recently saw some strange behavior with the Python kernel-doc. I was
seeing the verbose info lines from the kernel-doc script, i.e.:

> Info: ice_ptp_hw.c:5377 Scanning doc for function ice_cgu_get_pin_freq_supp
> Info: ice_ptp_hw.c:5406 Scanning doc for function ice_cgu_get_pin_name
> Info: ice_ptp_hw.c:5441 Scanning doc for function ice_cgu_state_to_name
> Info: ice_ptp_hw.c:5463 Scanning doc for function ice_get_dpll_ref_sw_status
> Info: ice_ptp_hw.c:5505 Scanning doc for function ice_set_dpll_ref_sw_status
> Info: ice_ptp_hw.c:5544 Scanning doc for function ice_get_cgu_state
> Info: ice_ptp_hw.c:5612 Scanning doc for function ice_get_cgu_rclk_pin_info
> Info: ice_ptp_hw.c:5671 Scanning doc for function ice_cgu_get_output_pin_state_caps
> Info: ice_ptp_hw.c:5733 Scanning doc for function ice_ptp_lock
> Info: ice_ptp_hw.c:5770 Scanning doc for function ice_ptp_unlock
> Info: ice_ptp_hw.c:5782 Scanning doc for function ice_ptp_init_hw
> Info: ice_ptp_hw.c:5811 Scanning doc for function ice_ptp_write_port_cmd
> Info: ice_ptp_hw.c:5834 Scanning doc for function ice_ptp_one_port_cmd
> Info: ice_ptp_hw.c:5866 Scanning doc for function ice_ptp_port_cmd
> Info: ice_ptp_hw.c:5901 Scanning doc for function ice_ptp_tmr_cmd
> Info: ice_ptp_hw.c:5934 Scanning doc for function ice_ptp_init_time
> Info: ice_ptp_hw.c:5986 Scanning doc for function ice_ptp_write_incval
> Info: ice_ptp_hw.c:6035 Scanning doc for function ice_ptp_write_incval_locked
> Info: ice_ptp_hw.c:6056 Scanning doc for function ice_ptp_adj_clock
> Info: ice_ptp_hw.c:6107 Scanning doc for function ice_read_phy_tstamp
> Info: ice_ptp_hw.c:6134 Scanning doc for function ice_clear_phy_tstamp
> Info: ice_ptp_hw.c:6164 Scanning doc for function ice_ptp_reset_ts_memory
> Info: ice_ptp_hw.c:6183 Scanning doc for function ice_ptp_init_phc
> Info: ice_ptp_hw.c:6215 Scanning doc for function ice_get_phy_tx_tstamp_ready
> Info: ice_ptp_hw.c:6247 Scanning doc for function ice_check_phy_tx_tstamp_ready
> Info: ice_ptp_hw.c:6273 Scanning doc for function ice_ptp_config_sfd
> Info: ice_ptp_hw.c:6293 Scanning doc for function refsync_pin_id_valid

I didn't understand why I was seeing this as it should only be happening
if running kernel-doc in verbose mode. Then I discovered I had set
KBUILD_VERBOSE=0 in my environment.

The python kernel-doc implementation reads this in the __init__ for
KernelFiles() on line 165:

>         if not verbose:
>             verbose = bool(os.environ.get("KBUILD_VERBOSE", 0))

After some debugging, I realized this reads KBUILD_VERBOSE as a string,
then converts it to a boolean using python's standard rules, so "0"
becomes true, which enables the verbose output.

This is in contrast to the (now removed) kernel-doc.pl script which
checked the value for a 1:

>  if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'KBUILD_VERBOSE'} =~ '1') 
The same behavior happens if you assign V=0 on the command line or to
any other non-empty string, since when V is set on the command line it
sets KBUILD_VERBOSE.

Of course, I can remove KBUILD_VERBOSE from my environment, I'm not
entirely sure when or why I added it.

Would think it would make sense to update the kdoc_files.py script to
check and interpret the string value the same way the perl script used
to? It seems reasonable to me that users might set "V=0" thinking that
it disables the verbosity. Other verbosity checks are based on the
string containing a 1, (some even use 2 for even more printing).

I'm not entirely sure what the best implementation for python is to
avoid this misinterpretation, so I haven't drafted a proper patch yet.

Thanks,
Jake