Stencil: docs: missing docs for various features

[Hotell]

So after a long time I came back to skim stencil docs, and again got confused by undocumented behaviors. This issue is a report of things that I didn't find answer to within the docs or just got confused by missing explanation :)

@Prop options

• What does connect option do? https://github.com/ionic-team/stencil/blob/bcc579ae9ad40e0a5737d31832141185e57fbf7a/src/declarations/decorators.ts#L30
  
  
  
  • related: what is this doing @Prop({ connect: 'ion-menu-controller' }) lazyMenuCtrl: Lazy<MenuController>; ?
  
  
• reflectToAttr: true how will casing work here ? ( I assume camelCase -> dash-case )
• where should be reactions to prop change executed ? within method decorated by @Watch or within componentWillUpdate LC hook?
• add context docs to prop + reference to Context guide

@Component() options

• how does styleUrls object resolution work ?

@Component({
  tag: 'ion-something',
  // this will be loaded by default
  styleUrl: 'something.scss',
  // how does following work ?
  styleUrls: {
    ios: 'something.ios.scss',
    md: 'something.md.scss',
    wp: 'something.wp.scss'
  }
})

Special Class methods

• document hostData from style-guide chapter

  /**
   * 11. hostData() function
   * Used to dynamically set host element attributes.
   * Should be placed directly above render()
   */
  hostData() {
    return {
      attribute: 'navigation',
      side: this.isRightSide ? 'right' : 'left',
      type: this.type,
      class: {
        'something-is-animating': this.isAnimating
      }
    };
  }

ShadowDOM

• what will happen in non nativeShadow DOM browsers if component uses this.el.shadowRoot.querySelector() for getting data imperatively within stencil component? Will it be transformed in runtime as fallback with CSS or it will throw and error and user is responsible to handle this on his own

Expected behavior:

• document all public API and guides mentioned above

related: https://github.com/ionic-team/stencil/issues/891

[adamdbradley]

Any assistance with improving the docs would be appreciated. The repo can be found here: https://github.com/ionic-team/stencil-site

[Hotell]

I would love to contribute to the docs, but how could I, when I don't have answers to all questions that I've asked? 🤔😶

[jlarmstrongiv]

For those coming after me wondering how styleUrls work, I found this blogpost to be helpful.

[ShawnTalbert]

I'm a bit amazed that the .d.ts files don't include documentation. Having jsdocs on these declarations would go a long way towards an in-IDE reference.

[jlarmstrongiv]

Some more information on PropOptions for context. Couldn’t find anything on PropOptions for attr and connect though.

[manucorporat]

Context and connect were not documented for good reason, in stencil one are finally deprecated!!