Programming In Perl Writing Documentation Shawn Pearce Software Design

1
Programming In Perl Writing DocumentationShaw
n PearceSoftware Design DocumentationThere
s documentation in them thar hills!
2
Why Document?

• Help Users (user manual)
• Convey Assumptions
• Known Bugs/Issues
• Jog Your Memory
• Get Hit By A Bus Syndrome

3
Types of Documentation

• User Manual
• End Users
• Administrators Manual
• More Technical
• Developers Manual
• API Documentation
• Style/Best Practice Guides

4
Types of Documentation

• Use Cases
• Domain Model Diagrams
• Static Class Diagrams
• Behavior (Interaction/State) Diagrams

5
Example - Step 1Requirements, Use-Case Model

• Use Case UC1 Play Cup Game
• Primary Actor Player, Dealer
• Main Success Scenario
• 1. Player puts ball under cup
• 2. Dealer moves cups
• 3. Player picks cup
• a. If ball is under cup then they win
• b. Else they lose

6
Example Domain Model
7
Example - Interaction Diagram
8
Example - Class Diagram
9
Example Program
package CupGame sub new my class
shift my self cups gt new
Ball, new Ball,
new Ball, ball gt new Ball,
dealer new Dealer, bless self,
class sub shuffle_cups my self
shift local _ _-gtmove forach
_at_self-gtcups
10
Documentation Formats

• Online Help
• Electronic Book PDF, HTML
• UNIX man Page
• Context Sensitive Help
• Offline Help
• Typically Stored On A Dead Tree/Forest
• Typically Weighs A Lot

11
Online Pros/Cons

• Pros
• Cheap To Distribute
• Easy On Demand Access
• Less Index/Table of Contents Effort Required
• Cons
• Harder To Read For Some Users
• Could Be Hard To Print

12
Offline Pros/Cons

• Pros
• Easier For Less Technical Users to Read
• Traditional Format
• Cons
• Expensive To Distribute
• Weight/Volume
• Good Index/Table of Contents REQUIRED

13
Know Your Audience

• Average Joe User
• Not Technically Skilled
• May Or May Not Know The Domain
• Developer
• Technical
• May Or May Not Know The Domain
• Yourself
• Technical
• Hopefully Know The Domain

14
Introducing POD

• POD eq Plain Old Documentation
• Thank Larry Wall.
• Intermixed With Perl Source
• Good For API Documentation
• Examples DBI, CGI, All Of CPAN ?

15
POD Syntax

• 1
• __END__
• head1 NAME
• CGI - Simple Common Gateway Interface Class
• head1 SYNOPSIS

16
Formatted POD

• CGI(3) User Contributed Perl Documentation
• NAME
• CGI - Simple Common Gateway Interface
• Class
• SYNOPSIS

17
Format Code Syntax

• Section Format Codes
• Prior Line Must Be Blank
• Must Start In Column 0/1
• Must Start With
• Character Format Codes
• Must Appear In Text
• Single Character
• Examples IltFOOgt, BltFOOgt, FltFOOgt

18
Start/End POD

• head1 FOO Start Section
• cut End Documentation
• These are magical in Perl It tells perl when to
  stop and restart parsing the file.
• FOO Tells us the title of the section.

19
API Doc In POD

• head2 DELETING A PARAMETER COMPLETELY
• query-gtdelete('foo','bar','baz')
• This completely clears a list of parameters.
• head2 DELETING ALL PARAMETERS
• query-gtdelete_all()

20
API Doc In POD

• DELETING A PARAMETER COMPLETELY
• query-gtdelete('foo','bar','baz')
• This completely clears a list
• of parameters.
• DELETING ALL PARAMETERS
• query-gtdelete_all()

21
Reading POD

• If Installed
• perldoc CGI
• perldoc MyModule
• If Not Installed
• perldoc ../CGI-3.04/CGI.pm
• perldoc MyModule.pm

22
For More Infomation

• perldoc perldoc
• perldoc perlpod
• Dont Forget The Ole Student Standby
• mail bauerd_at_cs.rpi.edu