Re: Discoverable documentation
Posted: Thu Jan 09, 2014 6:34 pm
Without being able to put my finger on it, I also found the documentation on Cobra a bit fragmented and confusing. In some areas, this is sort of an assumption that you are already familiar with C# syntax(1), in others it's the absence of certain type references(2), and in others it's assuming that I know Cobra primitives like usage of the print statement (3)(4)
So I'm not necessarily sold on "all on one page", as I think that'd be cluttered. But a reference document that separates but links to a useful builtin reference for C# (where still required) and Cobra primitives, a relevant library reference for C# (even a link to offsite Mono/.NET documentation) and Cobra stdlib, and perhaps a description of what you can and can't do in Cobra that you might like to do; you can pass references to methods in Cobra, but can you assign a method reference to a class variable on the fly? Can you dynamically generate classes, is there such a thing as a "class factory"? How about nested classes?
(1) List syntax (List<of whatever>), references to C# types like IDictionary (but I learned by accident that there's also "Dictionary", so what's the difference between that an IDictionary? Cobra assumes I know this already..), etc.
(2) like non-string byte arrays; in Python, these are "bytes", in Cobra apparently it's "uint8[](length)"; is there a dynamic or literal way to do bytes, like the b'' syntax in Python?
(3) Which I found documented on the wiki, but not in the samples beyond the total basic and obvious literal usage.
(4) Is there a rationale for why print is a literal? I find that major difference between Py2 and Py3 to be a huge selling point for Py3: I can inject a reference to a conditional shim function in Py3 for a "debug" mode and then litter my code with normal print statements, later deactivating them with a single line.. or passing "print" around as an argument, because it's a function. Why did Cobra go with print-as-statement when the Python guys decided that was a big mistake, and most people seemed to agree?
So I'm not necessarily sold on "all on one page", as I think that'd be cluttered. But a reference document that separates but links to a useful builtin reference for C# (where still required) and Cobra primitives, a relevant library reference for C# (even a link to offsite Mono/.NET documentation) and Cobra stdlib, and perhaps a description of what you can and can't do in Cobra that you might like to do; you can pass references to methods in Cobra, but can you assign a method reference to a class variable on the fly? Can you dynamically generate classes, is there such a thing as a "class factory"? How about nested classes?
(1) List syntax (List<of whatever>), references to C# types like IDictionary (but I learned by accident that there's also "Dictionary", so what's the difference between that an IDictionary? Cobra assumes I know this already..), etc.
(2) like non-string byte arrays; in Python, these are "bytes", in Cobra apparently it's "uint8[](length)"; is there a dynamic or literal way to do bytes, like the b'' syntax in Python?
(3) Which I found documented on the wiki, but not in the samples beyond the total basic and obvious literal usage.
(4) Is there a rationale for why print is a literal? I find that major difference between Py2 and Py3 to be a huge selling point for Py3: I can inject a reference to a conditional shim function in Py3 for a "debug" mode and then litter my code with normal print statements, later deactivating them with a single line.. or passing "print" around as an argument, because it's a function. Why did Cobra go with print-as-statement when the Python guys decided that was a big mistake, and most people seemed to agree?