[Pulp-dev] Redundancy in docstrings and serializer help_text

Austin Macdonald austin at redhat.com
Thu Aug 17 19:33:06 UTC 2017


On Tue, Aug 15, 2017 at 5:20 PM, Jeff Ortel <jortel at redhat.com> wrote:

> I'm not convinced, this is a good idea.
>
> The docstrings on the models document the data model.  The docstrings in
> the serializers document the REST
> resource model.  They are two different things.  Although in the pulp
> case, there isn't much difference (maybe
> none), it still seems wrong to conflate the two.  Also, the audience is
> different.  For the models, the
> audience is developers.  For the serializers, it's the API user.
>

When I started the work to align the docstrings/help_text with our MVP I
found it awkward to maintain slightly different wording of the same
information in two places.

Down the road, if there is practical value we are missing (like wanting to
explain it differently to different audiences), we can always make that
change. It won't be any more work to write different docstrings later, but
it will be more work to keep them identical for now.


>
> On 08/09/2017 01:48 PM, Austin Macdonald 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
> >
>
>
> _______________________________________________
> 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/20170817/72818446/attachment.htm>


More information about the Pulp-dev mailing list