On 08/19/2014 09:35 PM, Krystian Bacławski wrote: > What would you like to read in the documentation?
May I ask you the same question? Suppose *you* get some code that is in an area where you are not exactly an expert. What would *you* like to read first? You can now project that on me and then tell me that your code is only for experts. OK, that rules me out and I will then of course not even start to read your code. If, however, you want your code to live then you should explain what your code actually does. Make a running example and explain where your typechecker throws in valuable information for the spad compiler to pick up. And maybe you also explain why this extra information is advantageous for the following compilation step. In short, do as you would do when you write an article. Explain why your work is important. What's the state before your work, what's the state after your project has finished? Where is the real benefit. That would be the first "overview documentation" to guide someone through your project. That each domain and function signature should have a proper ++ docstring goes without saying. How else would you be able to prove that your code does what you expect it to do? > The algorithm is not fixed yet, on the contrary, it sometimes > undergoes brutal restructuring to accommodate new features. Clearly a > detailed documentation is a waste of time. I can describe high-level > architecture which is not very likely to change. I'd expect that after reading your documentation (not the code) it becomes clear what your code is really doing, how the flow of information is, how you gather all the information that you add to the AST, etc. etc. I don't necessarily expect logical formulae. It's often much more valuable to explain first in an informal way for a *human* to understand quickly. (Maybe I write nonsense here, but I'm not an expert and have no other knowledge about the project than the short GSoC description.) If you think it's a waste of time to write documentation, then you probably understand that you cannot expect anybody to waste his time trying to understand (and review) your code. You would have to wait for an expert with tons of time. Good luck. I don't say more. My position wrt. documentation is certainly not new. Ralf -- You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" 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/fricas-devel. For more options, visit https://groups.google.com/d/optout.
