On Tue, Aug 15, 2017 at 5:20 PM, Jeff Ortel <jor...@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@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 > >
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev
