FrameChangeObserver abstract class is hard to find in docs.

[DanRathbun]

The FrameChangeObserver abstract class is hard to find in the docs., and does not appear in the Class List.

Unlike ALL other observers, it uses (weirdly) a class method of the Pages collection class to attach and detach the observer. The explanation of how to use the observer is encapsulated in the attachment method Pages::add_frame_change_observer.
See: http://ruby.sketchup.com/Sketchup/Pages.html#add_frame_change_observer-class_method

[thomthom]

Yea, that observer is a strange one. I'm not sure why it attaches to the Pages class itself.

Personally I think that observer deserve its own page. I'll see if I can find some time the next new days to get something set up similar to how the Tool class is documented.

[DanRathbun]

I actually have a file for this 80% complete.

[thomthom]

I have set up the necessary work for YARD to generate a page for the FrameChangeObserver.

If you want to pass me what you have I can merge it in. Or, I can push the stubs for what I have and you can merge in your changes. Either way works for me.

[DanRathbun]

Attaching "FrameChangeObserver.rb" renamed to txt.

Look it over manually. I normally use markdown in my docs. So:

• All inline code (variable names) uses backticks, like: `method_name`.
  You might use + delimiters ?

• For the frameChange() callback method doc'ing, I used
  the YARD directive @!method tag as a test.

  • If you think it'll cause issues, remove it and add the method stub.

FrameChangeObserver.rb.txt

---

Just a FYI,... all 3 of my YARD installs are broken. I did something on the advice of the YARD author Mr. Segal, and it broke my YARDs. It was something about linking to the master so I could have the most up to date pushes. (At that time, he was behind in releasing some fixes, that I'd hoped would fix the external file including.) Anyway, it didn't work, and I cannot generate updated new docs. Last night trying to update the YARD gem failed for all 3 Rubies (2.0, 2.1 and 2.2)

So I cannot even see what the attached doc looks like LOCALLY in YARD.

[thomthom]

Thanks, I'll transpose it over to our internal docs manually and regenerate the docs and stubs.

As for YARD, I had to use the latest from master myself a while ago, but since then the gem was updated so I could go back to use that instead. How long ago was the fixes you need made?

[DanRathbun]

@thomthom: Thanks, I'll transpose it over to our internal docs manually and regenerate the docs and stubs.

Feel free to simplify the example even more if possible. I will have an even more expanded edition that has both AppObserver and PagesObserver callbacks in it (ie, a true hybrid observer,) ... to attempt to keep the @prev_scene from ever referencing a deleted entity.
But it was way to "busy" for an inline example.

[DanRathbun]

As for YARD, I had to use the latest from master myself a while ago, but since then the gem was updated so I could go back to use that instead. How long ago was the fixes you need made?

I don't know, as he kept saying that the {include} file bug was in another gem (the one that parsed markdown?) It is moot anyway as doing so broke YARD, and I could not run yardoc at all.

It's been over a year and a half since I last regenerated the "ydb" (my custom name for the "yardoc" database folder) and the "doc" folders.

No big loss, as I was playing around with multiple separate versioned "ydb" sub-folders, thinking along the lines of how the SketchUp Help center works with the version picker on the upper right.
But I realized that it makes more sense to have one doc set, and use the YARD @group tag to separate method summaries for different SketchUp versions or sources (ie DCUtils.) The full method treatments still appear in the correct alphabetical order in the Method Details List and the Method Index, but appear in their own entitled collapsible summary at the top of the page.

Here is an example using a "dcutils.rb" stub, that wraps the methods in each class, in a tag thus:
@group Methods added by "su_dynamiccomponents/ruby/dcutils.rbs"
(I was hoping the "added" group notes would appear inline with the summary group, but are ignored. At that time summary groups do not have their own freeform text. Maybe still not. And the notes would need to be moved up to precede the class declaration ?)
Group.zip.txt

Anyway, I have to re-organize my api project for one edition, and perhaps wipe out my Ruby installs and re-install.

[thomthom]

Btw Dan, I updated Ruby on my machine from 2.0 to 2.2 and with that got Yard 0.9.8 installed. That versions added an extra IFRAME in the index page. I had to roll back to 0.9.5 in order to get the output to be correct again; gem install yard -v 0.9.5

[thomthom]

That framechange class example of tracking the previous page, I think that would fit better in a wiki page. It's quite long and not that a simple example. We can use the wiki features of GitHub repos to create a page - then refer to a possible solution to the known bug from the doc.

[thomthom]

I added the base for a page on the FrameChangeObserver. The docs and stubs are live now. It might very well be improved upon, but at leave we now have the foundation to document it. I'm closing this issue as solved as the class is now found as a separate page in the docs.

[DanRathbun]

@thomthom

That framechange class example of tracking the previous page, ...
... It's quite long and not that a simple example.

Yea, it's is amazing the amount of code needed to workaround this 10 year old bug, that never gets fixed ! I am working on a even longer example that uses a module instead of a class, since the view object appears to be global and shared between models, there really is no good reason to use a class and instantiate an instance object. (It will eliminate the initialize method, etc.)

---

Did you not notice that I had changed the names of the first two arguments from the old docs?
from_page --> from_scene
to_page --> to_scene

You just pasted in the old examples with the old names.

[thomthom]

Ah, sorry about that. I'm visiting the Boulder office this month and my schedule is filled with meetings. I merged your changes in a bit of a hurry. Will need to fix that.