lsegal/yard — pull request #395 by kou (2011-10-13 04:22:50+00:00)
Title: Support pot output.

This change adds pot formatter.

Here is a sample transcript:

% ruby -I lib bin/yardoc --format pot --output po lib/**/*.rb
Files: 135
Modules: 37 ( 5 undocumented)
Classes: 148 ( 32 undocumented)
Constants: 62 ( 25 undocumented)
Methods: 680 ( 78 undocumented)
84.90% documented
% head po/yard.pot
# YARD::ROOT
#: ../lib/yard.rb:4
msgid "The root path for YARD source libraries"
msgstr ""

# YARD::TEMPLATE_ROOT
#: ../lib/yard.rb:7
msgid "The root path for YARD builtin templates"
msgstr ""

Translators generates #{LOCALE}.po from yard.pot. For example, here is a transcript that generates ja.po from yard.pot:

% LANG=C msginit --locale ja --input po/yard.pot --output po/ja.po
The new message catalog should contain your email address, so that users can
give you feedback about the translations, and so that maintainers can contact
you in case of unexpected technical problems.

Is the following your email address?
kou@clear-code.com
Please confirm by pressing Return, or enter your email address.
kou@clear-code.com
Retrieving http://translationproject.org/team/index.html... done.
A translation team for your language (ja) does not exist yet.
If you want to create a new translation team for ja, please visit
http://www.iro.umontreal.ca/contrib/po/HTML/teams.html
http://www.iro.umontreal.ca/contrib/po/HTML/leaders.html
http://www.iro.umontreal.ca/contrib/po/HTML/index.html
po/yard.pot:10858: warning: The following msgid contains non-ASCII characters.
This will cause problems to translators who use a character encoding
different from yours. Consider using a pure ASCII msgid instead.
YARD is a documentation generation tool for the Ruby programming language.
It enables the user to generate consistent, usable documentation that can be
exported to a number of formats very easily, and also supports extending for
custom Ruby constructs such as custom class level definitions. Below is a
summary of some of YARD's notable features.
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10858: invalid multibyte sequence
po/yard.pot:10868: warning: The following msgid contains non-ASCII characters.
This will cause problems to translators who use a character encoding
different from yours. Consider using a pure ASCII msgid instead.
Feature List
------------

**1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be compatible
with RDoc formatting. In fact, YARD does no processing on RDoc documentation
strings, and leaves this up to the output generation tool to decide how to
render the documentation.
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10868: invalid multibyte sequence
po/yard.pot:10880: warning: The following msgid contains non-ASCII characters.
This will cause problems to translators who use a character encoding
different from yours. Consider using a pure ASCII msgid instead.
**2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages**:
YARD uses a '@tag' style definition syntax for meta tags alongside regular code
documentation. These tags should be able to happily sit side by side RDoc formatted
documentation, but provide a much more consistent and usable way to describe
important information about objects, such as what parameters they take and what types
they are expected to be, what type a method should return, what exceptions it can
raise, if it is deprecated, etc.. It also allows information to be better (and more
consistently) organized during the output generation phase. You can find a list
of tags in the {file:docs/Tags.md#taglist Tags.md} file.
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10880: invalid multibyte sequence
po/yard.pot:10889: warning: The following msgid contains non-ASCII characters.
This will cause problems to translators who use a character encoding
different from yours. Consider using a pure ASCII msgid instead.
YARD also supports an optional "types" declarations for certain tags.
This allows the developer to document type signatures for ruby methods and
parameters in a non intrusive but helpful and consistent manner. Instead of
describing this data in the body of the description, a developer may formally
declare the parameter or return type(s) in a single line. Consider the
following Yardoc'd method:
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10889: invalid multibyte sequence
po/yard.pot:10925: warning: The following msgid contains non-ASCII characters.
This will cause problems to translators who use a character encoding
different from yours. Consider using a pure ASCII msgid instead.
# Reverses the contents of a String or IO object.
#
# @param [String, #read] contents the contents to reverse
# @return [String] the contents reversed lexically
def reverse(contents)
contents = contents.read if respond_to? :read
contents.reverse
end

With the above @param tag, we learn that the contents parameter can either be
a String or any object that responds to the 'read' method, which is more
powerful than the textual description, which says it should be an IO object.
This also informs the developer that they should expect to receive a String
object returned by the method, and although this may be obvious for a
'reverse' method, it becomes very useful when the method name may not be as
descriptive.

**3. Custom Constructs and Extensibility of YARD**: YARD is designed to be
extended and customized by plugins. Take for instance the scenario where you
need to document the following code:

class List
# Sets the publisher name for the list.
cattr_accessor :publisher
end

This custom declaration provides dynamically generated code that is hard for a
documentation tool to properly document without help from the developer. To
ease the pains of manually documenting the procedure, YARD can be extended by
the developer to handle the `cattr_accessor` construct and automatically create
an attribute on the class with the associated documentation. This makes
documenting external API's, especially dynamic ones, a lot more consistent for
consumption by the users.
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10925: invalid multibyte sequence
po/yard.pot:10942: warning: The following msgid contains non-ASCII characters.
This will cause problems to translators who use a character encoding
different from yours. Consider using a pure ASCII msgid instead.
YARD is also designed for extensibility everywhere else, allowing you to add
support for new programming languages, new data structures and even where/how
data is stored.

**4. Raw Data Output**: YARD also outputs documented objects as raw data (the
dumped Namespace) which can be reloaded to do generation at a later date, or
even auditing on code. This means that any developer can use the raw data to
perform output generation for any custom format, such as YAML, for instance.
While YARD plans to support XHTML style documentation output as well as
command line (text based) and possibly XML, this may still be useful for those
who would like to reap the benefits of YARD's processing in other forms, such
as throwing all the documentation into a database. Another useful way of
exploiting this raw data format would be to write tools that can auto generate
test cases, for example, or show possible unhandled exceptions in code.
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence
po/yard.pot:10942: invalid multibyte sequence

Created po/ja.po.

Those warning messages are caused by "U+2028" (LINE SEPARATOR) characters in README.md. LINE SEPARATOR isn't included in ASCII charset.