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

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

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