<div dir="ltr">This seems like a good approach. I'd summarize it as:<div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>How does that sound?</div><div><br></div><div>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.</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Aug 9, 2017 at 2:48 PM, Austin Macdonald <span dir="ltr"><<a href="mailto:austin@redhat.com" target="_blank">austin@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">I propose that we remove fields from the docstrings of our models with serializers and exclusively use the help_text of the serializers.<div><br></div><div>Reasons:</div><div>1. docstrings and help_text contain identical information. </div><div>2. help_text will become documentation, so we have to use it.</div><div>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.</div><div><br></div><div>I have done this for importers in this PR:</div><div><a href="https://github.com/pulp/pulp/pull/3117" target="_blank">https://github.com/pulp/pulp/<wbr>pull/3117</a></div><div><br></div></div>
<br>______________________________<wbr>_________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/<wbr>mailman/listinfo/pulp-dev</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><p style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important"><span style="margin:0px!important;padding:0px!important">Michael</span> <span style="margin:0px!important;padding:0px!important">Hrivnak</span></p><p style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important"></p><span style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important"><span style="margin:0px!important;padding:0px!important">Principal Software Engineer</span><span style="margin:0px!important;padding:0px!important">, <span style="margin:0px!important;padding:0px!important">RHCE</span></span> </span><span style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px"></span><br style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important"><p style="color:rgb(0,0,0);font-family:overpass-mono,monospace;font-size:10px;margin:0px!important;padding:0px!important">Red Hat</p></div></div>
</div>