Documentation: return types for built-in `ds` functions

[alanisaac]

I am experimenting with Topaz, and found it difficult to figure out what the results of functions like ds.object, ds.relation, and ds.graph are for use in rego policies. I pieced together some of it through experimentation, but if possible, it would be very helpful to have output schemas documented on this page: https://www.topaz.sh/docs/directory/built-ins

[gertd]

@alanisaac The first pass of fixes is available at https://deploy-preview-197--topaz-sh.netlify.app/docs/directory/built-ins

This cleans up the input structures, and documents the obsolete built-ins, and adds references to the API input and response shapes.

Let me know if this helps?

[alanisaac]

Yes that helps!

I might have a slight preference for documenting the outputs on the page, much like the inputs are. For example, take ds.object. The inputs are shown like so:

ds.object({
  "object_type": "<object type>",
  "object_id": "<object identifier>",
  "with_relation": <boolean>
})

Just for UX, it would be nice if the outputs were documented similarly so I don't have to navigate somewhere else, such as:

{
  "result": <result type>
  "relations": <relations type>
  "page": <pagination>
}

But that said -- I can get what I need out of the links, and it's much more understandable now! Thank you!