This seems like a good approach. I'd summarize it as: Try hard to put the documentation for each field of a model only on the corresponding serializer, which of course ends up being the API docs. That makes the API docs the primary source of truth.
In cases where there is something that is not appropriate for the API docs, not relevant to the API, or cannot be represented on the API (a field that's not exposed for example), then it should still be documented on the model. How does that sound? The one downside that stands out to me is that the field docs would not be convenient to view with the model fields themselves, but that might be a cost worth accepting. On Wed, Aug 9, 2017 at 2:48 PM, Austin Macdonald <aus...@redhat.com> wrote: > I propose that we remove fields from the docstrings of our models with > serializers and exclusively use the help_text of the serializers. > > Reasons: > 1. docstrings and help_text contain identical information. > 2. help_text will become documentation, so we have to use it. > 3. For master/detail models and serializers, fields are inherited so each > plugin awkwardly duplicates the fields into their docstrings. That is a lot > of duplication! Since serializers are inherited, help_text is inherited > too, and we can keep our docs/comments DRY and up to date. > > I have done this for importers in this PR: > https://github.com/pulp/pulp/pull/3117 > > > _______________________________________________ > Pulp-dev mailing list > Pulpemail@example.com > https://www.redhat.com/mailman/listinfo/pulp-dev > > -- Michael Hrivnak Principal Software Engineer, RHCE Red Hat
_______________________________________________ Pulp-dev mailing list Pulpfirstname.lastname@example.org https://www.redhat.com/mailman/listinfo/pulp-dev