[Pulp-dev] Redundancy in docstrings and serializer help_text

[Brian Bouterse]

+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 <mhrivnak at 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 <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
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20170811/33616a7c/attachment.htm>