>> Strife says: This function transforms the data, there is no expectation of modification, so the caveat isn't needed, though it is on other string and list function articles. I've been meaning to make a template.)
I would propose that for learners, who can make this mistake as I did many times when exhausted in the battle to learn LSL, that a caveat is useful, and that it does no harm for those who don't need it, as they can just ignore it? Part of my aim is to make the advice / language accessible to learners. As well, as you point out, it would be inconsistent not to have it here, as it is other similar places?
I like your idea of templating it, perhaps to appear as a definite Caveat that stands out, rather than something in a footnote?
Chaz Longstaff 17:36, 14 July 2008 (PDT)
- With functions like llListSort and llDeleteSubString a user coming from a language that does not have immutable lists and strings (very common) will have the expectation that these functions mutate the src parameter. But this expectation of mutation only exists for the purest of functions and to counter balance this is the expectation that the parameters won't be needlessly trashed by function calls. If llList2CSV were to mutate the src from a list into a string it would be trashing the parameter. Then there is the issue that LSL is strongly typed, there is no support for changing a variable type once it is declared (typecasts change the value after it has been copied from a variable, it doesn't actually do anything to the variable). Having this as a caveat gives the suggestion that LSL is not strongly typed.
- The template would just insert the text automatically into the caveats section. The advantage of this being that the text would be consistent across all articles.
- Really the immutability of lists and strings shouldn't be repeated on these pages but should be in the tutorials, type articles, and in a language specification about LSL. It's a universal rule of LSL that functions cannot modify the variables that provided the values for their parameters; we shouldn't be restating it everywhere. -- Strife Onizuka 19:16, 14 July 2008 (PDT)
- We generally aren't documenting what the functions don't do because if we were to document that, the documentation would be infinite (llListSort does not unclog drains for example or kill rodents). Our goal is to completely document everything that LSL does; not so much what it doesn't do. Once that is achieved, any user can read the documentation and know that if something isn't mentioned than it isn't something the language supports.
- Really it doesn't belong as a caveat or in the header but in the notes section. The only reason it is so high on the page is because it's such a common mistake. I see coders having problems with immutability all the time and if they actually took the time to read that far down the documentation there wouldn't be having problems.
- Idea: A new section for common mistakes: "Common Mistakes". Good idea? -- Strife Onizuka 20:27, 14 July 2008 (PDT)