Hi folks,
assume that some function/method produces files on the disk. What
should a doc test look like for such functions/methods? Is there a
standard? My fear is to have doc tests that destroy user data. I'd
like to know your opinion on my concerns.
1. The doc test would produce a file, even though the user didn't ask
for having nonsense data written onto his/her disk.
a) In what directory should the files be created? [Subdirectories
of] SAGE_TMP perhaps?
b) How can one avoid name conflicts with user data? E.g., in the doc
test for save_session, this point is not taken care of.
c) Should the doc test always end with removing the files (see doc
test for save_session)? Even if the test data are written into a
default location and are not nonsense but actually meaningful and
reasonable to keep?
d) Would an explicit removal of the files also be needed in
SAGE_TMP?
2. In view of 1.: Should such functions/methods have no doc test,
making an exception to the "100% doc test coverage" policy?
a) There is some evidence that the answer should be yes. For
example, there is no doc-test for 'file' or for 'os.mkdir'. However
these are not Sage but Python, and 'save_session' is a counter-
example.
b) In my case, 2.a) would mean to have *no* doc test *at all* in the
whole package. Not good.
Yours,
Simon
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-support@googlegroups.com
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/sage-support
URLs: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
