Menu
▾
▴
numpy-discussion
|
From: Charles R H. <cha...@gm...> - 2006-09-21 16:06:02
|
Travis, A few questions. 1) I can't find any systematic code testing units, although there seem to be tests for regressions and such. Is there a place we should be putting such tests? 2) Any plans for code documentation? I documented some of my stuff with doxygen markups and wonder if we should include a Doxyfile as part of the package. 3) Would you consider breaking out the Converters into a separate .c file for inclusion? The code generator seems to take care of the ordering. Chuck |
|
From: Sebastian H. <ha...@ms...> - 2006-09-21 16:18:08
|
On Thursday 21 September 2006 09:05, Charles R Harris wrote: > Travis, > > A few questions. > > 1) I can't find any systematic code testing units, although there seem to > be tests for regressions and such. Is there a place we should be putting > such tests? > > 2) Any plans for code documentation? I documented some of my stuff with > doxygen markups and wonder if we should include a Doxyfile as part of the > package. Are able to use doxygen for Python code ? I thought it only worked for C (and alike) ? > > 3) Would you consider breaking out the Converters into a separate .c file > for inclusion? The code generator seems to take care of the ordering. > > Chuck |
|
From: Louis C. <lco...@po...> - 2006-09-21 16:33:16
|
> Are able to use doxygen for Python code ? I thought it only worked for C (and > alike) ? There is an ugly-hack :) http://i31www.ira.uka.de/~baas/pydoxy/ But I wouldn't recommend using it, rather stick with Epydoc. -- Louis Cordier <lco...@po...> cell: +27721472305 Point45 Entertainment (Pty) Ltd. http://www.point45.org |
|
From: Charles R H. <cha...@gm...> - 2006-09-21 16:43:00
|
On 9/21/06, Sebastian Haase <ha...@ms...> wrote:
>
> On Thursday 21 September 2006 09:05, Charles R Harris wrote:
> > Travis,
> >
> > A few questions.
> >
> > 1) I can't find any systematic code testing units, although there seem
> to
> > be tests for regressions and such. Is there a place we should be putting
> > such tests?
> >
> > 2) Any plans for code documentation? I documented some of my stuff with
> > doxygen markups and wonder if we should include a Doxyfile as part of
> the
> > package.
>
> Are able to use doxygen for Python code ? I thought it only worked for C
> (and
> alike) ?
IIRC correctly, it now does Python too. Let's see... here is an example
## Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
Looks like ## replaces the /**
Chuck
|
|
From: Steve L. <lis...@ar...> - 2006-09-21 18:46:16
|
> Are able to use doxygen for Python code ? I thought it only worked
> for C (and
> alike) ?
>
> IIRC correctly, it now does Python too. Let's see... here is an
> example
> ## Documentation for this module.
> #
> # More details.
>
> ## Documentation for a function.
> #
> # More details.
> def func():
> pass
> Looks like ## replaces the /**
I never found it (although I haven't looked too hard), but I always
thought there was an official way to document python code --
minimally to put the documentation in the docstring following the
function definition:
def func(..):
"""One liner.
Continue docs -- some type of reStructredText style
"""
pas
Isn't that the same docstring that ipython uses to bring up help,
when you do:
In [1]: myobject.some_func?
So .. I guess I'm wondering why we want to break from the standard?
-steve
|
|
From: Robert K. <rob...@gm...> - 2006-09-21 19:24:39
|
Steve Lianoglou wrote: > So .. I guess I'm wondering why we want to break from the standard? We don't as far as Python code goes. The code that Chuck added Doxygen-style comments to was C code. I presume he was simply answering Sebastian's question rather than suggesting we use Doxygen for Python code, too. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco |
|
From: Charles R H. <cha...@gm...> - 2006-09-21 19:47:43
|
Hi,
On 9/21/06, Robert Kern <rob...@gm...> wrote:
>
> Steve Lianoglou wrote:
> > So .. I guess I'm wondering why we want to break from the standard?
>
> We don't as far as Python code goes. The code that Chuck added
> Doxygen-style
> comments to was C code. I presume he was simply answering Sebastian's
> question
> rather than suggesting we use Doxygen for Python code, too.
Exactly. I also don't think the Python hack description applies to doxygen
any longer. As to the oddness of \param or @param, here is an example from
Epydoc using Epytext
@type m: number
@param m: The slope of the line.
@type b: number
@param b: The y intercept of the line. The X{y intercept} of a
Looks like they borrowed something there ;) The main advantage of epydoc vs
doxygen seems to be that you can use the markup inside the normal python
docstring without having to make a separate comment block. Or would that be
a disadvantage? Then again, I've been thinking of moving the python function
docstrings into the add_newdocs.py file so everything is together in one
spot and that would separate the Python docstrings from the functions
anyway.
I'll fool around with doxygen a bit and see what it does. The C code is the
code that most needs documentation in any case.
Chuck
|
|
From: Alan G I. <ai...@am...> - 2006-09-21 23:57:32
|
On Thu, 21 Sep 2006, Charles R Harris apparently wrote: > As to the oddness of \param or @param, here is an example from > Epydoc using Epytext > @type m: number > @param m: The slope of the line. > @type b: number > @param b: The y intercept of the line. Compare to definition list style for consolidated field lists in section 5.1 of http://epydoc.sourceforge.net/fields.html#rst which is much more elegant, IMO. Cheers, Alan Isaac |
|
From: Travis O. <oli...@ie...> - 2006-09-21 16:30:30
|
Charles R Harris wrote: > Travis, > > A few questions. > > 1) I can't find any systematic code testing units, although there seem > to be tests for regressions and such. Is there a place we should be > putting such tests? All tests are placed under the tests directory of the corresponding sub-package. They will only be picked up by .test(level < 10) if the file is named test_<module_name>. .test(level>10) should pick up all test files. If you want to name something different but still have it run at a test level < 10, then you need to run the test from one of the other test files that will be picked up (test_regression.py and test_unicode.py are doing that for example). > > 2) Any plans for code documentation? I documented some of my stuff > with doxygen markups and wonder if we should include a Doxyfile as > part of the package. I'm not familiar with Doxygen, but would welcome any improvements to the code documentation. > > 3) Would you consider breaking out the Converters into a separate .c > file for inclusion? The code generator seems to take care of the ordering. You are right that it doesn't matter which order the API subroutines are placed. I'm not opposed to more breaking up of the .c files, as long as it is clear where things will be located. The #include strategy is necessary to get it all in one Python module, but having smaller .c files usually makes for faster editing. It's the arrayobject.c file that is "too-large" IMHO, however. That's where I would look for ways to break it up. The iterobject and the data-type object could be taken out, for example. -Travis |
|
From: David M. C. <co...@ph...> - 2006-09-21 19:20:51
|
On Thu, 21 Sep 2006 10:05:58 -0600 "Charles R Harris" <cha...@gm...> wrote: > Travis, > > A few questions. > > 1) I can't find any systematic code testing units, although there seem to be > tests for regressions and such. Is there a place we should be putting such > tests? > > 2) Any plans for code documentation? I documented some of my stuff with > doxygen markups and wonder if we should include a Doxyfile as part of the > package. We don't have much of a defined standard for docs. Personally, I wouldn't use doxygen: what I've seen for Python versions are hacks, whose output looks like C++, and which requires markup that's not like commonly-used conventions in Python (\brief, for instance). Foremost for Python doc strings, I think, is that it look ok when using pydoc or similar (ipython's ?, for instance). That means a minimal amount of markup. Someone previously mentioned including cross-references; I think that's a good idea. A 'See also' line, for instance. Examples are good too, especially if there's been disputes on the interpretation of the command :-) For the C code, documentation is autogenerated from the /** ... API */ comments that determine which functions are part of the C API. This are put into files multiarray_api.txt and ufunc_api.txt (in the include/ directory). The files are in reST format, so the comments should/could be. At some point I've got to through and add more :-) -- |>|\/|< /--------------------------------------------------------------------------\ |David M. Cooke http://arbutus.physics.mcmaster.ca/dmc/ |co...@ph... |
|
From: Alan G I. <ai...@am...> - 2006-09-21 23:57:32
|
On Thu, 21 Sep 2006, "David M. Cooke" apparently wrote: > Foremost for Python doc strings, I think, is that it look > ok when using pydoc or similar (ipython's ?, for > instance). That means a minimal amount of markup. IMO reStructuredText is very natural for documentation, and it is nicely handled by epydoc. fwiw, Alan Isaac |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X