40
Documenting from Trench Xavier Noria @fxn RuPy 2011

Documenting from the Trenches

Embed Size (px)

DESCRIPTION

 

Citation preview

Page 1: Documenting from the Trenches

Documenting from the TrenchesXavier Noria

@fxn

RuPy 2011

Page 2: Documenting from the Trenches
Page 3: Documenting from the Trenches
Page 4: Documenting from the Trenches

module Globalizeclass MigrationError < StandardError; endclass MigrationMissingTranslatedField < MigrationError; endclass BadMigrationFieldType < MigrationError; end

module ActiveRecordautoload :Adapter, ’globalize/active_record/adapter’autoload :Attributes, ’globalize/active_record/attributes’autoload :Migration, ’globalize/active_record/migration’

def self.included(base)base.extend ActMacro

end...

endend

Page 5: Documenting from the Trenches

Infer

Page 6: Documenting from the Trenches
Page 7: Documenting from the Trenches
Page 8: Documenting from the Trenches
Page 9: Documenting from the Trenches

Community Drivers

⋆ Documentation tools⋆ Imitation⋆ Leaders’ commitment

Page 10: Documenting from the Trenches

Perl

Page 11: Documenting from the Trenches
Page 12: Documenting from the Trenches
Page 13: Documenting from the Trenches

$ perldoc IO::String

Page 14: Documenting from the Trenches
Page 15: Documenting from the Trenches

$ perldoc perl

Page 16: Documenting from the Trenches
Page 17: Documenting from the Trenches
Page 18: Documenting from the Trenches
Page 19: Documenting from the Trenches

Literate Programming

Page 20: Documenting from the Trenches

Essayists

Page 21: Documenting from the Trenches

Works of Literature

Page 22: Documenting from the Trenches
Page 23: Documenting from the Trenches
Page 24: Documenting from the Trenches
Page 25: Documenting from the Trenches

docrails

Page 26: Documenting from the Trenches

Style

⋆ Typography⋆ Spelling⋆ Conventions

Page 27: Documenting from the Trenches

Content

⋆ Simple, concise exposition⋆ Comprehensive coverage⋆ Well-chosen examples⋆ Edge-cases⋆ Anticipation

Page 28: Documenting from the Trenches

Documenting ∼ Teaching

Page 29: Documenting from the Trenches

# actionpack/lib/action_controller/base.rbmodule ActionController

class Base < Metal...MODULES = [

AbstractController::Layouts,AbstractController::Translation,AbstractController::AssetPaths,

... about two dozen modules]

MODULES.each do |mod|include mod

end...

endend

Page 30: Documenting from the Trenches

# activerecord/lib/active_record/validations.rbmodule ActiveRecord

module Validationsextend ActiveSupport::Concerninclude ActiveModel::Validations

module ClassMethodsdef create!(attributes = nil, &block)

if attributes.is_a?(Array)attributes.collect { |attr| create!(attr, &block) }

elseobject = new(attributes)yield(object) if block_given?object.save!object

endend

end...

endend

Page 31: Documenting from the Trenches

<!DOCTYPE html><html><head>

<title>DefaultLayout</title><%= stylesheet_link_tag :all %><%= javascript_include_tag :defaults %><%= csrf_meta_tag %>

</head><body>

<%= yield %>

</body></html>

Page 32: Documenting from the Trenches

# Returns a meta tag with the cross-site request forgery protection# token for forms to use. Place this in your head.def csrf_meta_tag

if protect_against_forgery?%(<meta name=”csrf-param” content=”...”/>\n<meta ...>).html_safe

endend

Page 33: Documenting from the Trenches

# Returns a meta tag with the cross-site request forgery protection# token for forms to use. Place this in your head.def csrf_meta_tag

<<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery?<meta name=”csrf-param” content=”...”/><meta name=”csrf-token” content=”...”/>

METASend

Page 34: Documenting from the Trenches

# Returns meta tags ”csrf-param” and ”csrf-token” with the name# of the cross-site request forgery protection parameter and# token, respectively.## <head># <%= csrf_meta_tag %># </head>## These are used to generate the dynamic forms that implement# non-remote links with <tt>:method</tt>.## Note that regular forms generate hidden fields, and that Ajax# calls are whitelisted, so they do not use these tags.def csrf_meta_tag

<<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery?<meta name=”csrf-param” content=”...”/><meta name=”csrf-token” content=”...”/>

METASend

Page 35: Documenting from the Trenches

# Returns meta tags ”csrf-param” and ”csrf-token” with the name# of the cross-site request forgery protection parameter and# token, respectively.## <head># <%= csrf_meta_tags %># </head>## These are used to generate the dynamic forms that implement# non-remote links with <tt>:method</tt>.## Note that regular forms generate hidden fields, and that Ajax# calls are whitelisted, so they do not use these tags.def csrf_meta_tags

<<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery?<meta name=”csrf-param” content=”...”/><meta name=”csrf-token” content=”...”/>

METASend

Page 36: Documenting from the Trenches

# Returns meta tags ”csrf-param” and ”csrf-token” with the name# of the cross-site request forgery protection parameter and# token, respectively.## <head># <%= csrf_meta_tags %># </head>## These are used to generate the dynamic forms that implement# non-remote links with <tt>:method</tt>.## Note that regular forms generate hidden fields, and that Ajax# calls are whitelisted, so they do not use these tags.def csrf_meta_tags

<<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery?<meta name=”csrf-param” content=”...”/><meta name=”csrf-token” content=”...”/>

METASend

# For backwards compatibility.alias csrf_meta_tag csrf_meta_tags

Page 37: Documenting from the Trenches

Documentation Maintenance

Page 38: Documenting from the Trenches

$ ack csrf_meta_tag

Page 39: Documenting from the Trenches

Wish List

⋆ Load + introspect for API⋆ Link API and tests⋆ Test coverage for guides

Page 40: Documenting from the Trenches

Thanks