Migrate the documentation from Hiki to YARD

[dubstep]

Hi,

I would like to migrate the documentation from Hiki to YARD.
So, I made a tool, and uploaded files to
Ruby-GNOME 2 - Browse /yard at SourceForge.net.

• yagi_gnome-0.0.1.pre.gem
  a tool to automate tasks and source parser(still incomplete)
• vte-1.0.0.gem
  example package with YARD style comments
• vte-doc.tar.bz2
  example YARD documents

Migration steps:
1.Change the Rules like vte.

• Change file name to like ‘rbvte-terminal.c’
• Change file header comments
• Define RG_TARGET_NAMESPACE macro
• Use RG_DEF_* macros
  2.Embed YARD style comments from GIR(GObject Introspection),
  and add ‘@todo fixme’ tag.
  3.Fix the comments referring to Hiki documents and the source code,
  and delete ‘@todo fixme’ tag.

Will be able to use the following:
$ gem install yagi_gnome
$ gem install vte
$ yard config -a autoload_plugins gnome
$ yard server -g
Go to http://localhost:8808/.

But there are some problems:

• yagi_gnome support only Ruby 1.9.2 or later.
• Documents aren’t generated on Windows, because gem is binary package.
• YARD server is too slow.

I have a few questions.

• What do you think of this migration steps?
• Could you help me migration step3?

Thanks,

yagi(Masaaki A.)

[Masaaki_A]

Migration steps:
1.Change the Rules like vte.

• Change file name to like ‘rbvte-terminal.c’

Is changing file names really needed?
Not that I care much but it makes following project history harder
when all files are suddenly renamed at some point.

$ gem install vte
$ yard config -a autoload_plugins gnome
$ yard server -g
Go to http://localhost:8808/.

But there are some problems:

• yagi_gnome support only Ruby 1.9.2 or later.

It’s quite OK. 1.8.7 support would be nice but one thing at a time.

• Documents aren’t generated on Windows, because gem is binary package.

It should still be possible to get the sources or perhaps include the
docs in the binary gem or something.

• YARD server is too slow.

How slow? Slower than SF? It’s quite hard to beat SF in that regard.
Even if slow it is quite helpful when the help can be browsed locally.
Also can’t some alternative server display the pages?

Thanks

Michal

[Masaaki_A]

In principle I am fine with this.

A few comments though:

• Right now I can update the wiki (ko1 gave me the password and login
  years ago) and I do so every now and then fixing little things. Will
  this be easy on YARD too? The wiki is very, very helpful for ruby-gnome.
  Without it, I could not have started with ruby-gnome.

• Will there still be a remote wiki that people can watch and browse
  though? This is very useful for me right now.

[Masaaki_A]

Hi,

Sorry for late reply.

• Right now I can update the wiki (ko1 gave me the password and login
  years ago) and I do so every now and then fixing little things. Will
  this be easy on YARD too?

Yes, probably.

• Will there still be a remote wiki that people can watch and browse
  though?

It is still to be determined.

Thanks,

yagi

[Masaaki_A]

Hi,

Sorry for late reply.

• Change file name to like ‘rbvte-terminal.c’

Is changing file names really needed?
Not that I care much but it makes following project history harder
when all files are suddenly renamed at some point.

Changing file names is not really needed for this migration.
But yagi_gnome includes feature to generate source files from GIR, and
it needs naming rules.
So, I would like to change file names.

• Documents aren’t generated on Windows, because gem is binary package.

It should still be possible to get the sources or perhaps include the
docs in the binary gem or something.

• YARD server is too slow.

How slow?

It depends on conditions(number of methods, inherited class, included
modules, and others).

Also can’t some alternative server display the pages?

We will probably distribute generated docs(like vte-doc.tar.bz2)
and/or serve the pages.

Thanks,

yagi

[Masaaki_A]

On Fri, Sep 23, 2011 at 13:29, Masaaki A. [email protected]
wrote:

• Change file name to like ‘rbvte-terminal.c’

Is changing file names really needed?
Not that I care much but it makes following project history harder
when all files are suddenly renamed at some point.

Changing file names is not really needed for this migration.
But yagi_gnome includes feature to generate source files from GIR, and
it needs naming rules.
So, I would like to change file names.

I’m not happy about having to change the names, but I think the naming
should follow that in the relevant library that we are wrapping, and
if we can get things for free, then changing the names of files is
definitely worth it.

On the C side, Atk, GIO/GLib/GObject, goocanvas, GStreamer, Gtk,
GtkSourceView, and Vte all use the atkaction.c style.

Gdk-pixbuf, Pango, librsvg use the gdk-pixbuf-animation.c style.

Poppler is written in C++ and uses the PopplerCache.cc style.

(The gdk_pixbuf2 library should really have been called gdk-pixbuf2,
but that’s beside the point.)

My opinion is that we should follow the first style, namely
atkaction.c. If there is any value in adding a “rb” prefix, then
fine, call it rbatkaction.c. I’ve never seen the value of adding yet
another prefix, however, so I didn’t do so for gio2.

Whatever we decide, I think that we should have one rule that applies
to all files in the project.

[Masaaki_A]

On Tue, Sep 20, 2011 at 16:46, Masaaki A. [email protected]
wrote:

• yagi_gnome-0.0.1.pre.gem
  a tool to automate tasks and source parser(still incomplete)

Please take the following criticism as my thoughts only. I think that
this tool has a lot of potential and I would to see it be used for the
Ruby-GNOME2 project. I think that a tool like this is necessary for
us to be able to bring the documentation up to the quality that we
desire.

The coding style isn’t like the standard:

• You use a tabwidth of 2 instead of spaces
• You use a “_” prefix for method parameters
• You use explicit return
• You define constants that only act as shortcuts to other constants,
  for example, CO = YARD::CodeObjects
• You define multiple classes per file
• You use common prefixes for all methods in a class, which just gets
  in the way; see, for example, lib/yagni_gnome/template/code_object.rb
  (are you doing that because you’re monkey-patching YARD::CodeObjects?)

There are also a lot of singleton methods. I feel that such code is
begging for a refactoring. (Singleton objects in disguise.)

There’s also a lot of commented-out code.

You also monkey-patch String, which I don’t think is a very good thing
to do. There’s also a lot more monkep-patching going on, of, for
example, Hash, Nokogiri::XML::Node, YARD::Docstring.

[Masaaki_A]

On Fri, Sep 23, 2011 at 13:30, Masaaki A. [email protected]
wrote:

• Will there still be a remote wiki that people can watch and browse
  though?

It is still to be determined.

This is hardly a deal-breaker. Looking at the history, the wiki isn’t
being updated a lot.

Having the documentation with the code makes it so much easier to keep
them in sync.

[Masaaki_A]

Hi,

2011/9/23 Nikolai W. [email protected]:

My opinion is that we should follow the first style, namely
atkaction.c. If there is any value in adding a “rb” prefix, then
fine, call it rbatkaction.c. I’ve never seen the value of adding yet
another prefix, however, so I didn’t do so for gio2.

Currently, most files have “rb” prefix, so I think it is better to
follow.

Whatever we decide, I think that we should have one rule that applies
to all files in the project.

I agree with you.

I would like to change to rbatkaction.c style.
What do you think?

Thanks,

yagi

[Masaaki_A]

Hi,

2011/9/23 Nikolai W. [email protected]:

(are you doing that because you’re monkey-patching YARD::CodeObjects?)

There are also a lot of singleton methods. I feel that such code is
begging for a refactoring. (Singleton objects in disguise.)

There’s also a lot of commented-out code.

You also monkey-patch String, which I don’t think is a very good thing
to do. There’s also a lot more monkep-patching going on, of, for
example, Hash, Nokogiri::XML::Node, YARD::Docstring.

Thanks for your advice.
Will be helpful.

yagi

[Masaaki_A]

• You define constants that only act as shortcuts to other
  constants,for example, CO = YARD::CodeObjects

I do this a lot in my code. It is less to type and no way in
life will I type something as long as YARD::CodeObjects when
I could use something shorter (if I have to reuse it in my
project files).

I have not looked at the code though, just a general remark since
you seem to dislike that … I even go as far as do T = true and
F = false and use that for my larger projects. And alias e puts.

This probably makes other people crazy but I love it. And I
love that ruby does not want to enforce a specific style -
though with that being said, I try to not deviate from standard
ruby much and I try to be careful when “monkey patching”
anything (I myself do not really use this term, it sounds
derogative when it is in reality powerful to me)

• You define multiple classes per file

I agree! I think it is better if it is possible to follow
a simple scheme for this. I usually have one class per file,
and keep the file name as lowercased variant, with _ added.

Example:

class FooBar

Would be stored in the file:

foo_bar.rb

The big advantage here is that this scheme is VERY easy to
understand for everyone and very “logical”.

But I think this is all fairly minor, it’s just style.

As long as the resulting documentation is as useful as the wiki
is (and I love the ruby-gtk wiki, even though it is not perfect,
I get server errors when modifying the pages, even though it
works) then I think this is GREAT work by Masaaki A.!