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.
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 > [email protected] > https://www.redhat.com/mailman/listinfo/pulp-dev >
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Pulp-dev mailing list [email protected] https://www.redhat.com/mailman/listinfo/pulp-dev
