harvard-lil / capstone

CAP database scripts.
MIT License
188 stars 44 forks source link

Confusing documentation of the citation object #2174

Open cweider opened 1 year ago

cweider commented 1 year ago

The documentation for “Case” describes the content of citations as an “array of citation objects”. I was inclined to follow the spec under the “Citation” heading, but it does not describe what I see in the API. It’s likely that citations described refer to something else entirely – and don’t exist! A subsection for citation may need to be added to “Case” and the “Citation” section struck.

Documentation:

https://github.com/harvard-lil/capstone/blob/821fa7b846ca21e3b3420ce35bdb0f5738c0b8f9/capstone/capweb/templates/docs/04_specs_and_reference/02_data_formats.md?plain=1#L48-L59

https://github.com/harvard-lil/capstone/blob/821fa7b846ca21e3b3420ce35bdb0f5738c0b8f9/capstone/capweb/templates/docs/04_specs_and_reference/02_data_formats.md?plain=1#L292-L298

What an observe matches what I see in generating code of serializers.py – a dictionary with two keys: "type" and "cite".

Generating Code:

https://github.com/harvard-lil/capstone/blob/821fa7b846ca21e3b3420ce35bdb0f5738c0b8f9/capstone/capapi/serializers.py#L230

https://github.com/harvard-lil/capstone/blob/821fa7b846ca21e3b3420ce35bdb0f5738c0b8f9/capstone/capapi/serializers.py#L55-L58

In the documentation “Case” and “Citation” are sibling headings – could it be that “Citation” refers to a route? If it does, that route doesn’t exist anymore.

Routes:

https://github.com/harvard-lil/capstone/blob/821fa7b846ca21e3b3420ce35bdb0f5738c0b8f9/capstone/capapi/api_urls.py#L10-L20