snapcraft syntax documentation is incomplete

[Roger Peppe]

The "definitive" snapcraft.yaml documentation at http://snapcraft.io/docs/build-snaps/syntax does not mention some crucial pieces.

For example, it does not mention that an app entry under the "apps" section can have a "plugs" section (it's mentioned in http://snapcraft.io/docs/build-snaps/metadata), which is essential for knowing how to allow access to resources for an app.

Perhaps the definitive syntax could be automatically generated from something in the snapcraft source so that there's less danger of it becoming out of sync.