[Pulp-dev] Redundancy in docstrings and serializer help_text

[Michael Hrivnak]

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 <austin at 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 at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
>


-- 

Michael Hrivnak

Principal Software Engineer, RHCE

Red Hat
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20170810/67462cbe/attachment.htm>