[Pulp-dev] Redundancy in docstrings and serializer help_text

[Jeff Ortel]

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 847 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20170815/af31199c/attachment.sig>