On Sun, Mar 09, 2014 at 05:50:29AM -0700, Andrew wrote:
> I think that it is good that this is being done (thank you!) but, like
> some others, I'm not fond of the use of implicit code and black magic
> whenever this makes it hard to track down the real source of some of the
> code.
I belong to the "some others":-) I am the first one to be struck when
this happens!
The question is whether this ticket makes things worse in
practice. After having used it quite some, I believe not, especially
since I tweaked things to this end. But I'd love to have more feedback
arising from concrete use.
> If everything is well documented and explained then this is probably
> OK, although I feel that one of the problems with python/sage
> documentation is that we are encouraged to write good documentation for
> methods but there is little emphasis of writing a self-contained general
> overview of what is going on -- I've even had reviewers take this out when
> I have tried to write it.
I agree: we need more overview documents in Sage!
> To take the category framework as an example, I have fought with it and
> won on several occasions but it is always been a painful experience
> because I find that the documentation is not very helpful. Of course,
> perhaps it is just me but I find that most of the example code in the
> documentation is artificial and treats only simplified situations and that
> many little "secrets" are not documented at all.
> To be fair good documentation is hard to write, especially when
> you have a complex piece of code. Even so, in my experience there
> is quite a lot of undocumented magic in the category framework.
Concrete examples would be helpful so that we can see if it was
actually due to "black magic in the infrastructure" as is discussed
here. Or "just" a problem of navigating the large body of generic code
implemented in the categories; problem that we would have as well with
plain abstract classes. Of course in both cases we should seek to
improve things! In particular, each areas (modules, algebras, groups,
...) should have overview documents.
> I hope that the documentation for the functorial constructions patch is
> more helpful.
I put a lot of work into that :-) It would be helpful if you could
read the updated primer [1] and the overview documentation about
axioms [2] and report!
Cheers,
Nicolas
[1]
http://sage.math.washington.edu/home/nthiery/sage-6.0/src/doc/output/html/en/reference/categories/sage/categories/primer.html
[2]
http://sage.math.washington.edu/home/nthiery/sage-6.0/src/doc/output/html/en/reference/categories/sage/categories/category_with_axiom.html
--
Nicolas M. Thiéry "Isil" <nthi...@users.sf.net>
http://Nicolas.Thiery.name/
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
