search

deercreeklabs / lancaster

Apache Avro library for Clojure and ClojureScript
Other
60 stars 5 forks source link

Support for doc #5

Closed hiram-madelaine closed 5 years ago

hiram-madelaine commented 5 years ago

Hi ! Congratulation for your excellent work ! I plan to use your library to export a JSON schema including documentation. Do you plan to add the possibility to add doc to the fields ? Thank you very much

chadharrington commented 5 years ago

I have been working on a fairly large update to lancaster, which I hope to document and release next week some time. I can add doc support to that release. To make sure that the feature meets your needs, can you describe your use case for doc attributes? The more details that I have, the better I can match your needs.

hiram-madelaine commented 5 years ago

I just need to be able to output a JSON schema that include the doc attribute. Correct me if I am wrong but the vector syntax for the field can not accept the doc string as optional because of the default value ? I do not know if you planned to include the doc already ? There could be a map syntax with explicit fileds :name, :type, :doc, :default, :alias Or I was thinking also about adding a the docstring as a meta to use the vector syntax ?

(l/def-record-schema person-schema
                     ^{:doc "The doc is exported in the avro scheam"} [:name l/string-schema]
                     [:age l/int-schema])
chadharrington commented 5 years ago

I am thinking that an optional first doc argument would work fine in the tuple format, since it would be a string, e.g.:

(l/def-record-schema person-schema                     
                     ["This field is for the name" :name l/string-schema]
                     [:age l/int-schema])

Also, I plan to add docstring support to records and enums, e.g.:

(l/def-record-schema person-schema     
                     "This record describes a person..."                
                     ["This field is for the name" :name l/string-schema]
                     [:age l/int-schema])

I will add these changes sometime this week.

hiram-madelaine commented 5 years ago

Hi Chad, this is a great idea ! I am looking forward to seeing your next version.

chadharrington commented 5 years ago

I hoped to get to this during my vacation last week, but I did not. I am not sure when I will be able to get this implemented. It may be several weeks now. Sorry about that!

hiram-madelaine commented 5 years ago

Hi Chad ! No problem. I know, it is hard to managed OSS development with job and family ;-)

burbma commented 5 years ago

@hiram-madelaine it looks like this feature was added in this commit on this line and this line and documented at this point in the README. Here's an example:

  (l/def-record-schema person-schema
    "MY DOCSTRING"
    [:name "NAME DOCSTRING" l/string-schema]
    [:age l/int-schema])

  (l/json person-schema)
  ;; "{\"name\":\"user.Person\",\"type\":\"record\",\"fields\":[{\"name\":\"name\",\"type\":[\"null\",\"string\"],\"default\":null,\"doc\":\"NAME DOCSTRING\"},{\"name\":\"age\",\"type\":[\"null\",\"int\"],\"default\":null}],\"doc\":\"MY DOCSTRING\"}"

If you scroll sideways you can see the doc strings in the json.

@chadharrington this issue can probably be closed.

hiram-madelaine commented 5 years ago

Thank you very much !