<div dir="ltr"><div>+1 to adopting this idea. @mhrivnak your summary sounds good.<br><br></div>What is the next step to doing this?<br></div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Aug 10, 2017 at 11:36 AM, Michael Hrivnak <span dir="ltr"><<a href="mailto:mhrivnak@redhat.com" target="_blank">mhrivnak@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">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"><div><div class="h5">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></div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class="h5"><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/p<wbr>ull/3117</a></div><div><br></div></div>
<br></div></div>______________________________<wbr>_________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman<wbr>/listinfo/pulp-dev</a><br>
<br></blockquote></div><span class="HOEnZb"><font color="#888888"><br><br clear="all"><div><br></div>-- <br><div class="m_-4412331997041067252gmail_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>
</font></span></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></div>