Work in Progress: Adding docco comments to racer

[irnc]

As an continuation of a https://github.com/codeparty/derby/pull/159 here is a n attempt to document racer's internals.

This pull request should be considered as a work in progress for which help and corrections are needed.

[irnc]

@nateps @bnoguchi @codeparty What is your attitude towards such documentation? I think internals should be documented inline because it is hard to newcomers to understand how racer/derby works. And thus it is right to impossible for them to make fixes or additions to a platform.

[lefnire]

+1 times infinity. Both @irnc's racer & derby docs.

[Ziink]

+1

[switz]

+1 as well.

On Thursday, December 6, 2012 at 7:46 PM, Ziink wrote:

+1

— Reply to this email directly or view it on GitHub (https://github.com/codeparty/racer/pull/59#issuecomment-11113337).

[mattbrun]

+1 on the inline docco documentations, but I'd say that this kind of docs are just for the "pro" derby users (the kind of user who goes to the code to understand it if something doesn't work), not for those who want to use derby without knowing nuts and bolts about it... (the kind of user who choose another framework or asks someone else to fix it if something goes wrong).

Choosing to focus on the inline docs or the kind of docs as the derby home page or the wiki, in my opinion, depends on the kind of audience the project leaders would like to focus on. Personally I'd say that we need a strong and easy to use/understand basement for the "pro users", so that these users can make a good community also for the "not pro users".

Take my thoughts as thoughts, not as polemic argumentations ;)

[lefnire]

@irnc - had a conversation with @codeparty a while back about this docco stuff. Evidently Racer is undergoing a total overhaul, so the documentation here will also require an overhaul, is why they're holding off. I'd like to convince them to just merge this while it's here, as well as the Derby docco, and you can tackle the new Racer documentation when the time comes.

[irnc]

@lefnire Right now this pull request will fail to merge I guess, and I don't have time right now to merge and resolve conflicts. So I think it is better to wait, because this additions is work in progress (read crap :) anyway, and require additional work before merging.

So better to ask @codeparty to be more open with updates about their intentions and plans.

[lefnire]

Gotcha. Well, keep up the good work in any case. There are a few of us in the community who have a clone of your docco branches for documentation lookup, they're not unnoticed.

[nateps]

No longer relevant in 0.5