1 files changed, 148 insertions, 0 deletions
diff --git a/src/Javadoc-style_Perl_Documentation_Generator.adoc b/src/Javadoc-style_Perl_Documentation_Generator.adoc
new file mode 100644
index 0000000..83d82c8
--- /dev/null
+++ b/src/Javadoc-style_Perl_Documentation_Generator.adoc
@@ -0,0 +1,148 @@
+Javadoc-style Perl Documentation Generator
+==========================================
+:author: Aaron Ball
+:email: nullspoon@iohq.net
+
+
+== {doctitle}
+
+I'm not a huge fan of Java, but I really do appreciate their standards for code
+comments. I use them in my PHP, C+\+, and Perl code. There is obviously some
+changing that needs to happen becuase those languages don't all comment the
+same, but for the most part it works really well.
+
+Today I needed to write up a document on how one of my larger scripts/programs
+worked. I wanted to include the script architecture, but didn't have a good way
+to do it. Then I remembered something one of my favorite open source projects
+does. MediaWiki is doing continuous integration and so they use (as I know
+other OSS projects do) http://jenkins-ci.org/[Jenkins] to do post-commit
+validation.  Specifically relating to this post, they use the Jenkins scripts
+to verify that the comments for each function are in the right format and
+contain the right data types, etc. In application to my project at hand, in my
+Perl scripts this would look something like...
+
+----
+#
+# This subroutine does something cool
+#
+# @param $_[0] string This is a test parameter
+# @param $_[1] array This is an array reference of mic checks
+#
+# @return bool Success or failure of this function's awesomeness
+#
+----
+
+The commit validation scripts Jenkins uses would check if the subroutine
+definition did in fact require two parameters and that the function returned
+boolean. Granted, since Perl isn't strongly typed, this has to be a bit looser
+than it would for other languages (C+\+, C#, etc), but you get the idea. This
+documentation style is still awesome (at least, I think it is)
+
+What I needed today though was a script that parsed my other scripts, read in
+all the subroutines (Perl, remember?), parsed out the comments for each one,
+and returned HTML using inline styles so I could copy it into a Word (well,
+LibreOffice Writer) doc without losing formatting.  That said, here's the quick
+and dirty.
+
+**Note**: Ironically, I just realized that this script isn't commented.
+
+----
+#!/usr/bin/env perl 
+use warnings;
+use strict;
+ 
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+ 
+if( scalar( @ARGV ) < 1 ) {
+  print "\nPlease specify a file to parse.\n\n";
+  exit( 0 );
+}
+ 
+main( @ARGV );
+ 
+sub main {
+  my $path = $_[0];
+  # Open our file and do some science!
+  open FILE, $path or die $!;
+  my @lines = <FILE>;
+  close( FILE );
+  my @subs;
+  my $body = '';
+  for( my $i = 0; $i < scalar( @lines ); $i++ ) {
+    my $line = $lines[$i];
+    # Remove leading spaces
+    $line =~ s/^[\t\s]+//;
+    # Remove  multiple inner space
+    $line =~ s/[\t\s]+/ /;
+    if( $line =~ /^sub ([\d\w_-]+)[\s{]+$/ ) {
+      my $h2 = "<h2 style=\"margin:0px; padding:0px; display:inline; font-size:1.2em; color:#444;\">";
+      $body .= '<br />' . $h2 . $1 . "()</h2>\n";
+      # We've found one!
+      my $comments = '';
+      # Now we go backwards, nabbing the comments as we go
+      for( my $n = $i - 1; $n > 0; $n-- ) {
+        if( $lines[$n] =~ /#[\w\d\s\t]*/ ) {
+          # Becase we're now reading backwards,
+          # we need to prepend
+          $comments = lineToHtml( $lines[$n] ) . $comments;
+        } else {
+          # Exit and continue
+          $n = 0;
+        }
+      }
+      my $pStyle = "<p style=\"display:block; background-color:#eee; margin:0px;";
+      $pStyle .= "padding:5px; border:1px dashed #aaa; width:90%; font-size:9pt;\">";
+      $comments = $pStyle . $comments . "</p>\n";
+      $body .= $comments;
+    }
+  }
+  $body .= "\n\n";
+  print bodyToHtml( $body );
+  exit( 0 );
+}
+ 
+sub bodyToHtml {
+  my $body = $_[0];
+  my $bodyHeader = '<!DOCTYPE html />';
+  $bodyHeader .= '<html><head>';
+  $bodyHeader .= '</head><body style="font-family:sans-serif;">';
+
+  my $bodyFooter = '</body></html>';
+  return $bodyHeader . $body . $bodyFooter;
+}
+ 
+sub lineToHtml {
+  my $line = $_[0];
+
+  my $formatted = $line;
+  $formatted =~ s/^[#\s\t]+//;
+  $formatted =~ s/\n+//;
+  if( $formatted =~ /^\@param/ ) {
+    $formatted =~ s/\@param/<strong>\@param<\/strong>/;
+    $formatted = '<br /><span style="display:block; color:#499;">' . $formatted . '</span>';
+  } elsif( $formatted =~ /^\@return/ ) {
+    $formatted =~ s/\@return/<strong>\@return<\/strong>/;
+    $formatted = '<br /><span style="display:block; color:#494; margin-top:10px;">' . $formatted . '</span>';
+  }
+  $formatted =~ s/ (int|hash|array|string|boolean|bool) / <span style="color:#949; font-style:italic;">$1<\/span> /i;
+  $formatted .= "\n";
+  return $formatted;
+}
+----
+
+
+
+// vim: set syntax=asciidoc: