On Mon, May 24, 2010 at 6:17 PM, David Goldsmith <[email protected]>wrote:
> On Mon, May 24, 2010 at 4:59 PM, Charles R Harris < > [email protected]> wrote: > >> >> >> On Mon, May 24, 2010 at 2:11 PM, David Goldsmith <[email protected] >> > wrote: >> >>> On Mon, May 24, 2010 at 11:01 AM, Charles R Harris < >>> [email protected]> wrote: >>> >>>> Hi All, >>>> >>>> I'm wondering if we could extend the current documentation format to the >>>> c source code. The string blocks would be implemented something like >>>> >>>> /**NpyDoc >>>> """The Answer. >>>> >>>> Answer the Ultimate Question of Life, the Universe, and Everything. >>>> >>>> Parameters >>>> ---------- >>>> We don't need no stinkin' parameters. >>>> >>>> Notes >>>> ----- >>>> The run time of this routine may be excessive. >>>> >>>> """ >>>> */ >>>> int >>>> answer_ultimate_question(void) >>>> { >>>> return 42; >>>> } >>>> >>>> and the source scanned to generate the usual documentation. Thoughts? >>>> >>>> Chuck >>>> >>> >>> IMO it would be necessary to make such doc have the same status w.r.t. >>> the Wiki as the Python source; how much tweaking of pydocweb would that >>> require (Pauli is already over-committed in that regard; Joe, Perry, and I >>> are taking steps to try to alleviate this, but nothing is close to >>> materializing yet). I know that as far as Joe and I are concerned, getting >>> pydocweb to support a dual review process is a much higher, longer-standing >>> priority. >>> >>> Also, quoting from the docstring standard: "An optional section for >>> examples...while optional, this section is very strongly encouraged." >>> (Personally, I think this section should be required, not optional, for >>> functions, and methods which require their own docstrings.) But requiring >>> docwriters to supply working (i.e., compilable, linkable, runable) c code >>> examples (which would appear to be necessary because the coders appear to be >>> loath to provide their docstrings with examples) might be asking too much >>> (since we try to keep the doc writing effort open to persons at least >>> comfortable w/ Python, though not necessarily w/ c). >>> >>> Unless and until these concerns can be realistically and successfully >>> addressed, I'm a strong "-1". >>> >>> >> I'm not interested in having this part of the standard user documentation >> since the c functions are mostly invisible to the user. What I want is >> documentation for maintainers/developers of the c code. The c code is >> essentially undocumented and that makes it difficult to work with, >> especially for new people. At one time in the past I suggested using doxygen >> but that didn't seem to arouse much interest. I've also tried generating a >> call graph but only managed to crash the system... Anyway, it needs to be >> done at some point and I'm looking for suggestions. >> >> Chuck >> >> Not checking in un-/poorly documented new code would be a good start. > > So exactly how should the c code be documented? There is currently no documentation standard for c code. Chuck
_______________________________________________ NumPy-Discussion mailing list [email protected] http://mail.scipy.org/mailman/listinfo/numpy-discussion
