IOKit: Purpose and behavior of IORegistry::Init?

[mjbraun]

I have taken over code that I need to understand before I attempt to modernize and modify it. As a means to do so (and as a means to learn OS X programming, as I'm a rank amateur), I decided to document the code using Doxygen with the mentality that if I can't succinctly explain every class and method in the code, then I don't truly understand it enough to modify it (and also, I'm of the "Documentation is a Good Thing" camp). And yet I'm already running into problems and I was wondering if someone can help me understand what's going on in this particular case.

 

I have a class "ChangerBlockStorageDevice" (header/implementation) that inherits from the Apple classes (child-->parent) IOBlockStorageDevice-->IOService-->IORegistryEntry-->OSObject-->OSMetaClassBase. There is a method virtual bool ChangerBlockStorageDevice::init(OSDictionary *) that I'd like to document. The implementation basically sets one protected variable and then passes the OSDictionary (untouched) on to the superclass init. Now, obviously, I could waive my hands and just say the method "Initializes the object" and call it a day, but there's no value in that. So here are the questions I'm trying to figure out:

• When is init(OSDictionary) called and under what circumstances (and by "who")?
  
• What the nature of the OSDictionary parameter? How is it generated and consumed? Per the documentation for IORegistry::Init(OSDictionary *), it's "a dictionary that will become the registry entry's property table" but what does it actually contain and how are those values initially populated?
  
• Why might the previous developer have overridden init at all when, per Apple's comments, "This function is usually not overridden by developers." (I'd ask him, but he's unavailable).
  

And a bonus question:

• How might I better go about answering such questions on my own in the future?
  

I very much appreciate any help and/or guidance with both this particular question, as well as regarding my project in general and these forums (as I'm absolutely new here).