2015-06-08 9:51 GMT-05:00 Nathann Cohen <[email protected]>: > To me it is not a problem of doc but a problem of code. The issue is that > we have 99% of the poset functions in the poset/ folder, and a couple of > them in the category/ folder. If we move everything to posets, there's no > problem. I don't see any advantage in having poset code in a file that is > meant to implement the category of posets. >
I disagree with that. There's some advantage: if your code only depends on general mathematical properties of posets and not on the specific implementation of the poset object, then it should be in the category. The reason is: sometimes you define a parent (like a set of objects) which happens to have the mathematical property of a poset. Then it doesn't inherit from the actual poset object but does belong to the category of posets and you want to have access to the category methods. As to answer the original question, I would say the main goal of the documentation is to document primarily for users. So: what should I write so that the user understands how to use it, and where should I put it so that the user can see it. But or course, it happens sometimes that you have to add stuff specifically for the developers, especially to explain the code architecture. This is what I do when I comment some inner functions or parameters, or "private" (the ones starting with _ or __). I hope this comment helped. Best, Viviane > > Nathann > > > On Monday, June 8, 2015 at 4:27:29 PM UTC+2, Jori Mäntysalo wrote: >> >> There is some discussion at http://trac.sagemath.org/ticket/18534 . >> Maybe >> this could be a topic in this sage-devel list also. >> >> For now there is no list of "what can I do with these posets" -functions. >> That's because we have, for example, is_connected() on >> .../combinat/posets/posets.py and is_selfdual() on categories. And >> basically this is a question of viewpoint for documentation. Should we >> see >> it as documenting code, or as documenting functions for the user? >> >> -- >> Jori Mäntysalo >> > -- > 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 [email protected]. > To post to this group, send email to [email protected]. > Visit this group at http://groups.google.com/group/sage-devel. > For more options, visit https://groups.google.com/d/optout. > -- 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 [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
