Peter Alexander wrote: > On Fri, Oct 2, 2009 at 5:25 AM, Peter Alexander wrote: >> On Fri, Oct 2, 2009 at 5:13 AM, Dag Sverre Seljebotn wrote: >>> Robert Bradshaw wrote: >>>> No offense intended (as this was clearly marked as an experiment) but >>>> I have to admit this feels rather contrived, especially if we end up >>>> making classes/structuring code just to hold the docstrings of user- >>>> level abstractions.
+1 >>>> I think it would lead to a sparse scattering of >>>> documentation throughout the codebase (most of the code does *not* >>>> need to be exposed to the user documentation, e.g. all the Nodes that >>>> represent Python nodes, and most transforms). The comments/doctests >>>> in the code should probably be about the code itself (useful to a >>>> cython developer, but probably not to a cython user). >>>> >>> You may be right. (The one advantage is that it makes it easy to have >>> documentation for different versions of Cython.). That's an orthogonal problem and I find it unlikely that we will ever have to manage so many different Cython versions that the documentation becomes a bottleneck. >>> Thing is I need to have some "way of entry" into writing documentation >>> -- I must either think about the code that implements the feature, or >>> how I'd "tell people about it" directly in the docs. A pure MVC doesn't >>> give me that I think -- it would tend to just be another hierarchy to >>> remember just for the sake of it, when the hierarchy present in the docs >>> (the view) is the one I'm likely to know by heart. >>> >>> So I'm not sure I'd like to just dump a chunk somewhere if it is not in >>> the code, as I wouldn't get into the right "mood" by just dumping a >>> fragment somewhere (how do I find the fragment again later? At least >>> with the codebase I'd know where to look.) So I think I'm not a big >>> supporter of MVC with chunks as seperate files in a seperate directory. +1 >>> However, if all I have to do is submit trac tickets containing >>> documentation for a feature I just wrote, then I don't care much either way. I don't think that can be sufficient. If it's only about a set of examples, there's the Demos directory. If it's anything that needs more commentary and presentation, you'll have to make it fit into the docs somewhere and make sure people a) find it at the right place(s) when they look for it and/or read along, and b) understand what you want to bring across with the example in this specific context. The problem with MVC here is that the model isn't complete. The context (i.e. the view) is just as important. The same line of code can tell very different things depending on the text section you put it into. It'll be hard to write examples that are reused in multiple documents without impacting clarity and conciseness in any of them. The only niche I can think of where a simplified approach might make sense is optimisations. Something like "Since version x.y.z, Cython will recognise /this/ code pattern and translate it into efficient C code like /this/" might work well when put into an index. Everything else is best expressed in flowing text IMO. >> The thing that's different about Cython from the others, is that it's >> not a library which is API centric.. where extracting doc strings from >> the code source itself makes perfect sense. >> >> But, I don't feel that it's necessarily impractical in Cython's case >> either. It all depends on preference, I think. > > More... come to think of it.. all of Qt's documenation (including > technology elaborations, exaples and demos) reside within the source > code itself. They use "qdoc" to extract it to a view. This is what > DOxygen is modelled after which all though is primarily for API > extraction, is not solely for that purpose either. That certainly doesn't apply to Cython. A language needs a very different way of presentation than a simple mapping from an API implementation/spec to a doc index. Stefan _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
