Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Documenting from the Trenches

1,333 views

Published on

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Documenting from the Trenches

  1. 1. Documenting from the Trenches Xavier Noria @fxn RuPy 2011
  2. 2. module Globalize class MigrationError < StandardError; end class MigrationMissingTranslatedField < MigrationError; end class BadMigrationFieldType < MigrationError; end module ActiveRecord autoload :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
  3. 3. Infer
  4. 4. Community Drivers⋆ Documentation tools⋆ Imitation⋆ Leaders’ commitment
  5. 5. Perl
  6. 6. $ perldoc IO::String
  7. 7. $ perldoc perl
  8. 8. Literate Programming
  9. 9. Essayists
  10. 10. Works of Literature
  11. 11. docrails
  12. 12. Style⋆ Typography⋆ Spelling⋆ Conventions
  13. 13. Content⋆ Simple, concise exposition⋆ Comprehensive coverage⋆ Well-chosen examples⋆ Edge-cases⋆ Anticipation
  14. 14. Documenting ∼ Teaching
  15. 15. # 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
  16. 16. # activerecord/lib/active_record/validations.rbmodule ActiveRecord module Validations extend ActiveSupport::Concern include ActiveModel::Validations module ClassMethods def create!(attributes = nil, &block) if attributes.is_a?(Array) attributes.collect { |attr| create!(attr , &block) } else object = new(attributes) yield(object) if block_given? object.save! object end end end ... endend
  17. 17. <!DOCTYPE html><html><head> <title>DefaultLayout</title> <%= stylesheet_link_tag :all %> <%= javascript_include_tag :defaults %> <%= csrf_meta_tag %></head><body><%= yield %></body></html>
  18. 18. # 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
  19. 19. # 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
  20. 20. # 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
  21. 21. # 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
  22. 22. # 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
  23. 23. Documentation Maintenance
  24. 24. $ ack csrf_meta_tag
  25. 25. Wish List⋆ Load + introspect for API⋆ Link API and tests⋆ Test coverage for guides
  26. 26. Thanks

×