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
_______________________________________________ NumPy-Discussion mailing list [email protected] http://mail.scipy.org/mailman/listinfo/numpy-discussion
