Add missing Entity Documentation

[andrewsayre]

Many of our entity docs are incomplete! I'm using this issue to track the work remaining to flush out our entity documentation. Please help by picking one up and writing the docs!

Using cover as the standard:

• Specify the base entity class to inherit
• Describe properties and methods (which should be implemented/overridden)
• Describe consts (states, features, etc...)

Docs Needed (prioritized)

• [ ] Light - completely empty - @luismonge1192
• [ ] Media Player - incomplete
• [X] Climate - @willgreenberg #227
• [ ] Remote - completely empty
• [ ] Alarm Control Panel - incomplete
• [ ] Lock - completely empty
• [X] Fan - completely empty - @Angie1313 #229
• [ ] Camera - no existing page
• [ ] Calendar - no existing page

[iantrich]

Implement update() or async_update() to fetch data.

Should this only be async_update?

[andrewsayre]

Should this only be async_update?

It will depend on the library. The synchronous versions of commands (i.e. update()) are used when the implementation blocks execution.

[andrewsayre]

Just noticed we're missing an entire page for Camera.

[willgreenberg]

I've been looking into the code for Climate and it appears that most of the properties are defined but unfinished. Is the entity deprecated, or just needs work? I'll fill out the docs if it's still in use, and otherwise perhaps worth removing the documentation page for it?

If it's not deprecated: for those properties that aren't complete, most of them return None without specifying a type anywhere in the definition. Is it worth while to specify N/A or some other signifier and list them in the docs anyway? Could be a way to indicate which properties need work.

[luismonge1192]

I interested on updating/writing the light doc if no one has done so already

[Angie1313]

I will working on updating the documentation for the fan entity

[andrewsayre]

@willgreenberg Climate is alive and well. The page needs work. Don't confuse the default properties in the entity that should be implemented by the platforms. The docs should indicate the data type. We can also add a PR to add the type-hints once we've sorted this out. You'll want to look at some of the other climate platforms to see how they are used today.

@luismonge1192 and @Angie1313 rock on!! Thank you!!

[willgreenberg]

@andrewsayre Great, thanks. Now I see what you mean about default properties -- I'll dig into platforms using Climate to find the types for those unimplemented properties. Climate's on me!

[peteretep]

Calendar ? I see it in the code but nowhere in the docs, and I want to have a scheduler in a custom component

[RonSpawnson]

Working on "lock"

[RonSpawnson]

Lock entity documentation PR awaiting review: https://github.com/home-assistant/developers.home-assistant/pull/378