+1 to adopting this idea. @mhrivnak your summary sounds good. What is the next step to doing this?
On Thu, Aug 10, 2017 at 11:36 AM, Michael Hrivnak <mhriv...@redhat.com> wrote: > 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 >> Pulp-dev@redhat.com >> https://www.redhat.com/mailman/listinfo/pulp-dev >> >> > > > -- > > Michael Hrivnak > > Principal Software Engineer, RHCE > > Red Hat > > _______________________________________________ > Pulp-dev mailing list > Pulp-dev@redhat.com > https://www.redhat.com/mailman/listinfo/pulp-dev > >
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev