From 1885394214392349a92eaa959e5f6acdffcd2ca2 Mon Sep 17 00:00:00 2001
From: Aaron Ball <nullspoon@iohq.net>
Date: Sat, 4 Jul 2015 14:14:41 -0600
Subject: Restructured all posts

---
 ...avadoc-style_Perl_Documentation_Generator.ascii | 148 ---------------------
 1 file changed, 148 deletions(-)
 delete mode 100644 src/Javadoc-style_Perl_Documentation_Generator.ascii

(limited to 'src/Javadoc-style_Perl_Documentation_Generator.ascii')

diff --git a/src/Javadoc-style_Perl_Documentation_Generator.ascii b/src/Javadoc-style_Perl_Documentation_Generator.ascii
deleted file mode 100644
index 83d82c8..0000000
--- a/src/Javadoc-style_Perl_Documentation_Generator.ascii
+++ /dev/null
@@ -1,148 +0,0 @@
-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:
-- 
cgit v1.2.3