add support for documentation

[egonelbre]

It's difficult for the data team to figure out what each field means. Instead of needing to manually annotate, let's add comments directly to the database. That way tools should be able to read out that information.

https://www.postgresql.org/docs/current/sql-comment.html

[zeebo]

comments are hard. i tried recently to add comment support to the ast and failed. i don't remember why it was so hard, but one property that is challenging is that they can appear anywhere and i'd like the format command to be able to preserve them, so like every ast node that it parses could potentially need comments attached, which is a big undertaking.

[egonelbre]

I guess the primary thing we want is comments for tables and fields and indexes... maybe something like:

model baz (
    comment "baz table is the opposite of aay"
    key pk (comment "this is the almighty primary key")
    field pk serial64 (comment "the primary identifier")
    field a  int      ( default 50, comment "this shows the a-ness of the field" )
    field b  int      ( default 60 )
    field c  int      ( default 70 )
)

[zeebo]

that's much easier to do

[egonelbre]

There are some fields that have multiline comments, so not sure what to do about those... but potentially could fold it into a single string. e.g.

    // default_redundancy_algorithm is storj.RedundancyAlgorithm.
    // deprecated: in favor of global metainfo service settings.
    field default_redundancy_algorithm       int (updatable)

or

    // placement indicates how the objects should be stored in this bucket.
    // See storj.PlacementConstraint for the relevant information:
    //    0 - every country
    //    1 - EU
    //    2 - EEA
    //    3 - US
    //    4 - DE
    //    5 - Invalid, when there's no information about the placement.
    //    6 - NR (no Russia, Belarus or other sanctioned country)
    field placement int (nullable, updatable)