Skip to content

Commit

Permalink
fix typo. you win this round, holman!
Browse files Browse the repository at this point in the history
  • Loading branch information
mojombo committed May 23, 2010
1 parent a1cfad9 commit c4c666c
Showing 1 changed file with 1 addition and 1 deletion.
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ At first glance you'll notice a few things. First, and most important, is that t

Today's Ruby libraries suffer deeply from haphazard versioning schemes. Even RubyGems itself does not follow a sane or predictable versioning pattern. This lack of discipline stems from the absence of well defined Public APIs. TomDoc attempts to solve this problem by making it simple to define an unambiguous Public API for your library. Instead of assuming that all classes and methods are intended for public consumption, TomDoc makes the Public API opt-in. To denote that something is public, all you have to do is preface the main description with "Public:". By forcing you to explicitly state that a class or method is intended for public consumption, a deliberate and thoughtful Public API is automatically constructed that can inform disciplined version changes according to the tenets of "Semantic Versioning":http://semver.org. In addition, the prominent display of "Public" in a method description ensures that developers are made aware of the sensitive nature of the method and do not carelessly change the signature of something in the Public API.

Once a Public API has been established, some very exciting things become possible. We're currently working on a processing tool that will render TomDoc into various forms (terminal, HTML, etc). If you run this tool on a library, you'll get a printout of the Public API documentation. You can publish this online so that others have easy access to it. When you roll a new version of the library, you can run the tool again, giving it a prior version as a base, and have it automatically display only the methods that have changed. This diff will be extremely useful for users while they upgrade to the new version (or so they can evaluate whether an upgrade is warrented)!
Once a Public API has been established, some very exciting things become possible. We're currently working on a processing tool that will render TomDoc into various forms (terminal, HTML, etc). If you run this tool on a library, you'll get a printout of the Public API documentation. You can publish this online so that others have easy access to it. When you roll a new version of the library, you can run the tool again, giving it a prior version as a base, and have it automatically display only the methods that have changed. This diff will be extremely useful for users while they upgrade to the new version (or so they can evaluate whether an upgrade is warranted)!

While I've been using various nascent forms of TomDoc for several years, we're just now starting to adopt it for everything we do at GitHub. Now that I've formalized the spec it will be easy for the entire team to write compliant TomDoc. The goal is to have every class, method, and accessor of every GitHub library documented. In the future, once we have proper tooling, we'd even like to create a unit test that will fail if anything is missing documentation.

Expand Down

0 comments on commit c4c666c

Please sign in to comment.