EmptyEpsilon
EmptyEpsilon copied to clipboard
daid
Script reference ambiguity
There are several examples of this kind of ambiguity, but I'll just cite this one. For determining if shields are active, the current script reference looks like this:
It's a little ambiguous whether or not this is a stand alone function or one that is attached to something else. Admittedly, it kind of appears like it's attached to ShipTemplateBasedObject, but it's hard to tell when you look at the adjacent entries:
Also, it's hard to establish the relationship to ShipTemplateBasedObject just based on the formatting alone.
In the previous script reference, it was clear that the function should be part of a ship template based object:
It's good to know that the function returns a boolean, but it would also be good to know that the function should be attached to a ship template based object. Could we have it look more like this:
boolean ShipTemplateBasedObject getShieldsActive()
Could we have it look more like this: boolean ShipTemplateBasedObject getShieldsActive()
That wouldn't make much sense IMO, you would need the : as seperator, otherwise the relationships of the types boolean and ShipTemplateBasedObject won't be clear.
btw. It is still clear that getShieldsActive() is member of ShipTemplateBasedObject, as it's in the ShipTemplateBasedObject category, but I agree that it was more obvious in the older version.
I am also not sure what you mean by "when you look at the adjacent entries". The class is determined by the category (in this case ShipTemplateBasedObject), not by adjacent entries.
Are you referring to "ShipTemplateBasedObject setImpulseSoundFile"? That has nothing to do with the category, ShipTemplateBasedObject is just the type of the return value (like boolean in the other example). As the description says "Returns the object it was called on.", so that's why the return value is incidentally the same data type as the class of the function
I didn't notice that this was changed. But, I like the object object:setImpulseSoundFile(string) form the best, so the old method with return data info added to it.
Adjacent meaning the entry right before it and the entry right after it. The one before relates to the impulse sound and the one after relates to the shares energy with docked. Yes, the colon makes much more sense to be included as well. I didn't see any colons on any of the new stuff, so I was not sure if there was a reason for its omission.
I think I mentioned it in another context, but the all mono-spaced font all the time motif is a little harder to read in conjunction with the minimal indention. However, that's formatting, and not germane to this particular issue.
The reason I removed the class name in every method was so because it made return values look strange, especially if it's repeated
ShipTemplateBasedObject ShipTemplateBasedObject:setShieldsActive(boolean active)
The compromise was that I pinned the class header, so it always says where you are at the top of the page.
Also, global functions are not mixed in with the methods, they are all at the very top of the document
