Describe createCommentVNode in the API reference

[NataliaTepluhina]

createCommentVNode is not described anywhere on docs, so we need to add it

[leopiccionia]

It shouldn't be documented, because, according to Evan, it's internal only.

However, the docs still state that h(null, ...) returns a comment here, which is a mistake. Instead, it should mention somewhere that returning null in a render function creates a comment.

[skirtles-code]

The documentation has been changed but I'm still not sure whether it's quite right.

I had a play and it looks like there are two ways to create comments:

1. Using null in the array of children.
2. Returning null from a render function.

There are a couple of places where the documentation suggests creating a comment by using h(() => null). This does work but I don't believe it's really the special case it appears to be. From what I can tell that is just a functional component, with a render function that's returning null.

There is a use-case for creating comments as placeholders. If a component is rendered conditionally then it can help the VNode diffing algorithm to pair up nodes correctly. However, I'm unclear whether this is something we would want to document as using a key is more explicit. Perhaps there is an argument for documenting it to help render function authors to understand why some things work and others don't, despite appearing equivalent.

[skirtles-code]

PR #1006 adds documentation about returning null from a render function.

I think this can now be closed. There's plenty more we could add to the docs but I'm not sure there's anything else we should add. createCommentVNode itself doesn't appear to be part of the public API, so any further changes can be tracked in separate issues.