On Mon, May 24, 2010 at 4:59 PM, Charles R Harris <charlesr.har...@gmail.com > wrote:
> > > On Mon, May 24, 2010 at 2:11 PM, David Goldsmith > <d.l.goldsm...@gmail.com>wrote: > >> On Mon, May 24, 2010 at 11:01 AM, Charles R Harris < >> charlesr.har...@gmail.com> 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. DG
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion