Model#active_entities Should have Linked Return Type

[jimfoltz]

The Return type of the Model#active_entities method should link to the Sketchup::Entities docs.

This is true for many of the methods thoughout the site.

[thomthom]

Yes, a lot of methods is missing type info not only for return values but also param types. The reason for this is that with 1000+ methods it actually takes a long time to go through each and every one. We decided to launch as-is and incrementally correct this. Since we launched the new docs I've often made some sweeping corrections when fixing typos etc.

[jimfoltz]

I understand the amount of work it is. I wish there was a way we could make pull requests to help spread out the workload.

[thomthom]

I've been toying with YARD, learning more about it.

One thought I wanted to explore was if I could manage to write a tool that could take a Git diff (Pull Request) with changes made to the Ruby API stubs and place the comment back to it's original position in our CPP source. Not sure how feasible it is.

Another alternative we could try out in the short run; accept PR in the stubs repo, where we then copy+pasted the comment back our our CPP code manually. Making a script that convert the Ruby comment to CPP style comment would be trivial. Even that could be off loading some of this work for us - as we'd spend less time formatting. I have yet to fully test running YARD on the stubs though.

Some how I really want to figure out a system where user-improvements to the API docs can be near-automated.

Right now I have started using the stubs with RubyMine and I'm catching some mistakes like that - when I see it flagging a warning for a method that I know is correct.

[jimfoltz]

Can yard generate the docs from just the comments, or does it need to eval the Ruby source (stubs in this case) in order to build them?

[thomthom]

It doesn't eval any Ruby code, but it naively parse Ruby and C/C++ code to build it's database. So it would need the stubs for the method signature.

In some cases it can pick up RDoc declarations, but I wasn't always able to rely on that. For instance in parsing our C++ code I had to add some dummy code that was #ifdef'ed out for the compiler - just so that YARD could process it. For instance the Tool class - which isn't actually a class we define. It's just a meta-class.

[jimfoltz]

Discussion continued here:

http://forums.sketchup.com/t/ruby-api-docs-contributing/35656

[DanRathbun]

Can yard generate the docs from just the comments, or does it need to eval the Ruby source (stubs in this case) in order to build them?

Yes, YARD can generate method documentation from directive comments only (without stubs.)

See the directives in the YARD documentation:

• @!attribute
• @!method

(I echoed this to the forum discussion thread.)

[thomthom]

The method now document the return type.

[DanRathbun]

Just a note, that overhauling return types should be created as sub-project of the stubs repo.

[thomthom]

Yea, we'll have to organize the issues better when we have finally settled on the structure of this repos.

[jimfoltz]

Just a note, that overhauling return types should be created as sub-project of the stubs repo.

How would this be setup? Entering correct retun types is a primary enhancement for the documentation and navigation.

Edit - I see. GitHub has things named Projects to organize work.

[jimfoltz]

See #8