Upload
xavier-noria
View
1.048
Download
4
Embed Size (px)
DESCRIPTION
Citation preview
Documenting from the TrenchesXavier Noria
@fxn
RuPy 2011
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
Infer
Community Drivers
⋆ Documentation tools⋆ Imitation⋆ Leaders’ commitment
Perl
$ perldoc IO::String
$ perldoc perl
Literate Programming
Essayists
Works of Literature
docrails
Style
⋆ Typography⋆ Spelling⋆ Conventions
Content
⋆ Simple, concise exposition⋆ Comprehensive coverage⋆ Well-chosen examples⋆ Edge-cases⋆ Anticipation
Documenting ∼ Teaching
# 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
# 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
<!DOCTYPE html><html><head>
<title>DefaultLayout</title><%= stylesheet_link_tag :all %><%= javascript_include_tag :defaults %><%= csrf_meta_tag %>
</head><body>
<%= yield %>
</body></html>
# 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
# 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
# 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
# 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
# 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
Documentation Maintenance
$ ack csrf_meta_tag
Wish List
⋆ Load + introspect for API⋆ Link API and tests⋆ Test coverage for guides
Thanks