Some clarification on smart refresh

[davidfokkema]

A bit of clarification on how smart refresh works. It just calls the render() method of the widget where the reactive attribute is defined. It does nothing more. If you have a compound widget, that will not work and you'll need watch methods or use recompose.

Please review the following checklist.

• Docstrings on all new or modified functions / classes
• Updated documentation
• Updated CHANGELOG.md (where appropriate)

I did not update the changelog since nothing changed in the code.

[willmcgugan]

This isn't quite accurate. Compound widgets do have render methods, and they are called. Although for most compound widgets, the child widgets cover the parent fully so you never see that.

I've updated the initial paragraph, but I feel this may be too much information at this point. I don't like to have two admonitions next to each other. I also prefer to keep things as linear as possible within a single page, so we aren't encouraging the reader to jump down before they have read the initial text.

[davidfokkema]

Didn't know that the render method of compound widgets was actually called. Makes sense, but in my head, writing widgets, it was always either a render() method or a compose() method. But the one does not exclude the other.

I agree that too much information is not good, and two admonitions are a bit ugly. If you don't want users to jump ahead, I feel that a remark should be made in the relevant sections. I had a bit of trouble with smart refresh as well, and understanding that I should use a watch method for updating child widgets. The word "child" is only first mentioned in the recompose section. But, for most uses, you don't want to use recompose since that is not efficient for simply updating child widgets.