<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Aug 15, 2017 at 5:20 PM, Jeff Ortel <span dir="ltr"><<a href="mailto:jortel@redhat.com" target="_blank">jortel@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I'm not convinced, this is a good idea.<br>
<br>
The docstrings on the models document the data model.  The docstrings in the serializers document the REST<br>
resource model.  They are two different things.  Although in the pulp case, there isn't much difference (maybe<br>
none), it still seems wrong to conflate the two.  Also, the audience is different.  For the models, the<br>
audience is developers.  For the serializers, it's the API user.<br></blockquote><div><br></div><div>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. </div><div><br></div><div>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.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div class="m_155374847754752249gmail-HOEnZb"><div class="m_155374847754752249gmail-h5"><br>
<br>
On 08/09/2017 01:48 PM, Austin Macdonald wrote:<br>
> I propose that we remove fields from the docstrings of our models with serializers and exclusively use the<br>
> help_text of the serializers.<br>
><br>
> Reasons:<br>
> 1. docstrings and help_text contain identical information.<br>
> 2. help_text will become documentation, so we have to use it.<br>
> 3. For master/detail models and serializers, fields are inherited so each plugin awkwardly duplicates the<br>
> fields into their docstrings. That is a lot of duplication! Since serializers are inherited, help_text is<br>
> inherited too, and we can keep our docs/comments DRY and up to date.<br>
><br>
> I have done this for importers in this PR:<br>
> <a href="https://github.com/pulp/pulp/pull/3117" rel="noreferrer" target="_blank">https://github.com/pulp/pulp/p<wbr>ull/3117</a><br>
><br>
><br>
><br>
</div></div><div class="m_155374847754752249gmail-HOEnZb"><div class="m_155374847754752249gmail-h5">> ______________________________<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>
<br>
</div></div><br>______________________________<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><br></div></div>