DOC: some documentation on the new metadat api