I agree with Erik. > This distinction between docstrings vs. comments has never been the Sage > practice: Sage practice and official policy has always been to use > docstrings. Part of the point is that Sage has intentionally tried to blur > the line between user and developer, so any documentation should be made as > widely available, and as easily available, as possible. >
Perhaps this was a practice and reality when Sage was not mature. But for future and for better software, the right direction should be to make the line clear. I (We are) am not a user and a developer at the same time: When I am a user, I would see docstrings and help on a terminal or in a web browser. When I am a developer, I would read the comments in the file as well as the docstrings. When I am a user, I hate to see irrelevant implementation or development details. For original post and that particular example, I would add docstrings for all the four functions. -- 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 https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
