Documenting from the Trenches

1,188 views
1,143 views

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,188
On SlideShare
0
From Embeds
0
Number of Embeds
6
Actions
Shares
0
Downloads
1
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

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

×