> If you're developing, you're...not...looking at the code? That's how I'm > interpreting your comments. I don't see how it is possible to develop > without looking at the code. > > To reiterate, public documentation should be there for the user, internal > documentation (i.e. private methods) and comments are there for the > developers.
Travis, pardon me for saying so but recently I got the impression that your comments were a bit more close-minded than usual. What I said above, and the reason why Jori initiated this thread, is that documentation in the code is less readable than documentation in its HTML form. This is why our documentation is also compiled in html: because we can make drawings, use "itemize" environments, have text in bold, etc... By adding technical documentation at module level (under a section like "Technical details" or "Implementation"), we do not scare users away by providing useless information as we *claim* explicitly that this is only technical details. On the other hand, the developers (who are also users), may be interested to look at that. Even a user who just wonder "how it is implemented" may be interested in that. For "advertising purposes", it also lessens the barrier between "user" and "developers" as we try to encourage everybody to dig in and see how it works -- and become a contributor later. We need it to be more explicit. I have been working on Posets for a while, and Jori has been working on Posets for a while, and we never noticed this doc. Even for us, who are developers, documentation of the __init__ method was not sufficienty visible, and so we began to write a documentation that was... already there ! I would also be thankful if you eventually agreed that some people, like Jori and I, could expect to see this documentation advertised better, like at module level. As a result, and even though it may not be what you would do yourself, you could acknowledge that it cannot really hurt anybody in the end, and that it would solve the problem that Jori and I, and possibly others, met in the past or will meet in the future. Regards, Nathann -- 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.
