Feature Proposal: Add SMELL, FIXME and TODO report to PerlDoc
Motivation
The old
gendocs.pl
script highlighted all of the documented SMELLs, TODOs, and FIXMEs in the code. With the conversion to the
doc:
type include, we've lost some visibility to these.
Description and Documentation
Add this information into the
PerlDoc output. Show this information only if the user is in the
AdminGroup, just in case some of the smells might document an exploitable issue.
Examples
Impact
Implementation
+++ b/core/lib/Foswiki/IncludeHandlers/doc.pm
@@ -37,8 +37,10 @@ sub INCLUDE {
my $PMFILE;
open( $PMFILE, '<', $pmfile ) || return '';
- my $inPod = 0;
- my $pod = '';
+ my $inPod = 0;
+ my $howSmelly = 0;
+ my $pod = '';
+ my $isAdmin = Foswiki::Func::isAnAdmin();
local $/ = "\n";
while ( my $line = <$PMFILE> ) {
if ( $line =~ /^=(begin (twiki|TML|html)|pod)/ ) {
@@ -50,11 +52,22 @@ sub INCLUDE {
elsif ($inPod) {
$pod .= $line;
}
+ if ( $line =~ /(SMELL|FIXME|TODO)/ && $isAdmin ) {
+ $howSmelly++;
+ $pod .= " * $line";
+ }
+
}
close($PMFILE);
$pod =~ s/.*?%STARTINCLUDE%//s;
$pod =~ s/%STOPINCLUDE%.*//s;
+ $pod =
+ "<blockquote class=\"foswikiAlert\">"
+ . " *SMELL / FIX / TODO count: $howSmelly*\n"
+ . "</blockquote>"
+ . $pod
+ if $howSmelly;
$pod = Foswiki::applyPatternToIncludedText( $pod, $control->{pattern} )
if ( $control->{pattern} );
--
Contributors: GeorgeClark - 31 Dec 2010
Discussion
Great initiative
I somehow think TODO should be counted separately, as they shouldn't really be used for documenting defects. But this is still cool.
--
PaulHarvey - 31 Dec 2010
Thanks Paul. I pretty much duplicated the function in the old gendocs.pl script - highlighting any lines containing FIXME, SMELL or TODO (Anything else that should be matched?) and count them to report the total. There are probably several possible improvements (or flaws). It simply reports the matching lines as bullets following the most recent pod section. So if there are intervening subroutines without documentation, they are not identified. It could also probably pull out comments following the matching SMELL so that multi-line comments are captured.
--
GeorgeClark - 01 Jan 2011
Great idea! Very useful to zeroing in on things to do.
--
CrawfordCurrie - 01 Jan 2011