<br><br><div class="gmail_quote">On Sat, Jun 20, 2009 at 8:41 PM, David Goldsmith <span dir="ltr">&lt;<a href="mailto:d_l_goldsmith@yahoo.com">d_l_goldsmith@yahoo.com</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<br>
Thanks, Pierre, this is helpful, but the given example doesn&#39;t have any of the _other_ sections Functions have, though the docstring standard says &quot;all but Returns are relevant,&quot; so I&#39;m left wondering where to insert the &quot;new&quot; sections relative to the &quot;old.&quot;  (I know that not _all_ Function sections will always be relevant for _all_ classes, but I assume at least some of them will be relevant for some classes, but your example doesn&#39;t clarify where to put them.)  But, FWIW, thanks.<br>

</blockquote><div><br><br>Look at ndarray for an example: <a href="http://docs.scipy.org/numpy/docs/numpy.ndarray/#numpy-ndarray">http://docs.scipy.org/numpy/docs/numpy.ndarray/#numpy-ndarray</a><br><div class="gmail_quote">
<div>Documenting the class indeed means its __init__ function as far as Parameters, See Also, Examples, etc. This is what has been done so far for all classes I&#39;ve looked at. <br>
</div><div><br>
The Methods and Attributes sections show up automatically, and contain all public methods/attributes, so don&#39;t worry about putting a list of those in. Those methods/attributes do have their own docstrings.<br><br>Cheers,<br>
Ralf<br>
</div></div><br> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><br>
DG<br>
<br>
--- On Sat, 6/20/09, Pierre GM &lt;<a href="mailto:pgmdevlist@gmail.com">pgmdevlist@gmail.com</a>&gt; wrote:<br>
<br>
&gt; From: Pierre GM &lt;<a href="mailto:pgmdevlist@gmail.com">pgmdevlist@gmail.com</a>&gt;<br>
<div class="im">&gt; Subject: Re: [SciPy-dev] Doc-ing classes and data attributes<br>
&gt; To: &quot;SciPy Developers List&quot; &lt;<a href="mailto:scipy-dev@scipy.org">scipy-dev@scipy.org</a>&gt;<br>
</div>&gt; Date: Saturday, June 20, 2009, 5:06 PM<br>
<div><div></div><div class="h5">&gt;<br>
&gt; On Jun 20, 2009, at 7:23 PM, David Goldsmith wrote:<br>
&gt;<br>
&gt; &gt;<br>
&gt; &gt; Ok, a couple follow-up questions: where precisely<br>
&gt; should <br>
&gt; &gt; documentation of __init__, and the Attributes and<br>
&gt; Methods sections <br>
&gt; &gt; (when needed) go?  In other words,<br>
&gt; docstringstandard says, &quot;Use the <br>
&gt; &gt; same sections as outlined [for Functions],&quot; but as<br>
&gt; Functions don&#39;t <br>
&gt; &gt; have __init__, Attributes, or Methods, it is unclear<br>
&gt; where in the <br>
&gt; &gt; &quot;above&quot; template these new items should go.<br>
&gt;<br>
&gt; My 2c:<br>
&gt;<br>
&gt; * I don&#39;t document __init__, but I put a &#39;Parameters&#39;<br>
&gt; section in the <br>
&gt; docstring of the class that describes all the input<br>
&gt; parameters of <br>
&gt; __init__<br>
&gt; * Methods could be described in the docstring of the class,<br>
&gt; under a <br>
&gt; &#39;Methods&#39; entry, but it might be more appropriate to<br>
&gt; document them <br>
&gt; outside the class.<br>
&gt; * Same thing for Attributes: you could have a small list in<br>
&gt; the <br>
&gt; docstring, but as soon as you start documenting an<br>
&gt; attribute in <br>
&gt; detail, you&#39;d better have a separate section.<br>
&gt;<br>
&gt; Check <a href="http://pytseries.sourceforge.net/core.timeseries.html" target="_blank">http://pytseries.sourceforge.net/core.timeseries.html</a><br>
&gt; for an <br>
&gt; example of application.<br>
&gt;<br>
&gt;<br>
&gt; _______________________________________________<br>
&gt; Scipy-dev mailing list<br>
&gt; <a href="mailto:Scipy-dev@scipy.org">Scipy-dev@scipy.org</a><br>
&gt; <a href="http://mail.scipy.org/mailman/listinfo/scipy-dev" target="_blank">http://mail.scipy.org/mailman/listinfo/scipy-dev</a><br>
&gt;<br>
<br>
<br>
<br>
_______________________________________________<br>
Scipy-dev mailing list<br>
<a href="mailto:Scipy-dev@scipy.org">Scipy-dev@scipy.org</a><br>
<a href="http://mail.scipy.org/mailman/listinfo/scipy-dev" target="_blank">http://mail.scipy.org/mailman/listinfo/scipy-dev</a><br>
</div></div></blockquote></div><br>