Pro Yearly is on sale from $80 to $50! »

Документация (RogueConf 2013)

Документация (RogueConf 2013)

Лекция, в която представям възгледите си за писането на документация и няколко мои експериментални tool-чета за улесняване на процеса по документиране на код.

Видео: http://youtu.be/0aZ0LRxuq_I

Fc59401781a26b10f5d4fc5b758fb3b7?s=128

Andrew Radev

March 30, 2013
Tweet

Transcript

  1. Андрей Twitter: AndrewRadev Github: AndrewRadev Blog: andrewradev.com

  2. Vim

  3. Vim

  4. Документация

  5. Аз <3 документация

  6. READMEs

  7. Wikis

  8. Vim and :help

  9. man

  10. Понякога, аз !<3 документация

  11. # Returns true def public? return true end

  12. # Returns true def public? return false end

  13. Проблемите • Документацията повтаря кода • Документацията не се поддържа

  14. Самодокументиращ се код

  15. def a return bb[1] end

  16. # Returns the name # of the first day #

    of the week def a return bb[1] end
  17. def first_day_of_week return day_names[MONDAY] end

  18. Четим код > Документация

  19. Legacy code

  20. Четим код > Документация > Нечетим код

  21. Математики разни

  22. class RungeKutta attr_reader :h def initialize(h, f) @f = f

    @h = h.to_f end def call(x, y) k1 = h * f(x, y) k2 = h * f(x + h/2, y + k1/2) k3 = h * f(x + h, y - k1 + 2*k2) y + (1.0/6.0) * (k1 + 4*k2 + k3) end def f(*args) @f.call(*args) end end
  23. # Implements a third-order Runge-Kutta algorithm # for finding the

    solution to an ODE. # # See http://en.wikipedia.org/wiki/Runge_kutta class RungeKutta # ... end
  24. Sprockets

  25. Sprockets::Index

  26. module Sprockets # `Index` is a special cached version of

    # `Environment`. # # The expection is that all of its file system # methods are cached for the instances lifetime. # This makes `Index` much faster. This behavior # is ideal in production environments where the # file system is immutable. # # `Index` should not be initialized directly. # Instead use `Environment#index`. class Index < Base # ... end end
  27. The basic thing you need to get asset compilation working

    is an instance of `Environment`. That class implements the rack interface, so you could simply `run Sprockets::Environment.new` and get a rack server up that serves assets. For production use, you can use the `index` method to get an `Index` object, which is read-only and therefore faster.
  28. (demo)

  29. Имплементация • Repo • repo.url('lib/foo.rb') • tags • ctags_reader •

    Renderer • Ctags filename link → → • Ripper.lex • ObjectRegex
  30. Добра идея? • Нова информация • Знания за домейна •

    Остарява?
  31. Модули/класове, не функции

  32. Лесна за поддръжка

  33. Автомагическа документация!

  34. @include rake-tasks (demo)

  35. По-нататък: location, prerequisites

  36. @include sinatra(...) (demo)

  37. По-нататък: Ripper + ObjectRegex

  38. Pretty graphs! (demo)

  39. Имплементация • Regex-ове за връзките • Graphviz • Renderer •

    Base64-кодирана картинка
  40. None
  41. Автоматично или на ръка?

  42. Лесна за четене?

  43. Webpage

  44. CLI > Webpage (demo)

  45. Заслужава ли си?

  46. Заслужава ли си? • Библиотеки • Open Source • 3-ма

    души на монолитен рейлс app • SOA, 10+ човека
  47. Заслужава ли си tooling-а?

  48. Навици

  49. dawanda/doctools

  50. Въпроси?