I've recently started using jsdoc comments for documenting our javascript code, however I'm finding conflicting examples of the usage of the #param tag.
See https://code.google.com/p/jsdoc-toolkit/wiki/TagParam (PascalCase)
and https://developers.google.com/closure/compiler/docs/js-for-compiler (camel/lowercase).
camelCase makes sense to me since:
var foo = 1;
console.log(typeof foo); // outputs "number"
What's the correct casing to use for jsDoc #param comments? Or does it not matter? I'm planning to use it for document generation as well as running the code through google closure to get type checking.
Thanks!
The conflicting examples for JSDoc type expressions involve the JavaScript primitive types string, number and boolean, which have corresponding wrapper types: String, Number, and Boolean.
From Closure: The Definitive Guide:
The use of wrapper types is prohibited in the Closure Library, as
some functions may not behave correctly if wrapper types are used
where primitive types are expected.
See MDN: Distinction between string primitives and String objects.
Related
So Ive started learning Kotlin and I have a question about functions.
In Kotlin you can do the javascript thing of creating a variable that can hold any type. But functions need to have their parameters typed.
So is the practice in Kotlin to type all variables anyway?
Is it not kind of pointless allowing the variables to be untyped but forcing types for the parameters and return values of functions?
When you write
val x = "Pizza"
kotlin infers from the declaration that 'x' is a string, there isn't some magic going on, if you try
var x = "Pizza"
x = 42
it won't work, because x is of a type String.
kotlin translates to java, and java is a "Statically typed language", which means the type of a field have to be known at runtime,
other languages, like Javascript are a "Dynamically typed languages", which in them the variables types doesn't have to be known at runtime, so it can make the developer life a bit easier ( or harder ).
What does a single exclamation mark mean in Kotlin? I've seen it a few times especially when using Java APIs. But I couldn't find it in the documentation nor on StackOverflow.
They're called platform types and they mean that Kotlin doesn't know whether that value can or cannot be null and it's up to you to decide if it's nullable or not.
In a nutshell, the problem is that any reference coming from Java may be null, and Kotlin, being null-safe by design, forced the user to null-check every Java value, or use safe calls (?.) or not-null assertions (!!). Those being very handy features in the pure Kotlin world, tend to turn into a disaster when you have to use them too often in the Kotlin/Java setting.
This is why we took a radical approach and made Kotlin’s type system more relaxed when it comes to Java interop: now references coming from Java have specially marked types -- Kotlin Blog
It's the notation for platform types:
T! means "T or T?"
Platform Types
The type names or class names ending with single exclamation mark ! are called platform types in Kotlin. You find them when you are working in Kotlin with old Java code that doesn't contain nullability information.
Examples:
Nullable Information: Nullable Type
#Nullable String in Java is considered as String? by Kotlin.
Non-null Information: Non-null Type
#NotNull String in Java is considered as String by Kotlin.
No Information: Platform Type
String without annotations in Java is considered as String! by Kotlin.
How to deal with Platform Types?
You can work with a platform type either as a nullable or a non-null. The compiler will allow you to call all methods on this type. It’s your responsibility how to use them. If you know that the value can be null, you should compare it with null before you call methods on it. If you know it’s not null, you can use it directly but as in Java, you’ll get exception if your assumption about the nullability is wrong.
Note that you can't declare platform types in Kotlin code, they come only from Java code.
Inheritance and Platform Types
While overriding Java methods in Kotlin code, you have the option to declare parameters and return types as nullable or non-null. You need to choose this wisely, because if you decide to make the parameters non-null, the Kotlin compiler generates non-null assertions for these non-null parameters. And when next time you access this Kotlin code back from Java and you pass a null value, you'll get exception.
Hope that helps clearing all your doubts about Platform Types.
A Type notated with ! is called platform type, which is a type coming from Java and thus can most probably be null. It’s what the Kotlin compiler infers by default when calling Java (for the most basic cases, Java methods can be annotated to get around this). You should handle platform types as nullable types, unless you certainly know that the particular API will never return null. The compiler allows platform types to be assigned to variables of both nullable and non-null types.
Notation for Platform Types
[...]
T! means "T or T?" [...]
You could refer to platform types as "types of unknown nullability". Also important to know is that you cannot use the exclamation-marked type for your own types, it's not part of the Kotlin syntax, it's only a notation.
I use the funny interpretation to remember those things as below:
?: I dont know whether it is null or not.
!: Be careful! This might be null.
!!: Be careful, and yes I know it. This is always not null.
I've seen it a few times especially when using Java APIs
As mentioned by s1m0nw1, T! means T or T?. The next question is: what is T?? This is nicely documented at https://kotlinlang.org/docs/reference/null-safety.html. Kotlin does not allow certain elements to be null, e.g. String, unlike Java
To allow nulls, we can declare a variable as nullable string, written
String?:
var b: String? = "abc"
b = null // ok
[...]
b?.length
This returns b.length if b is not null, and null otherwise. The type of this expression is Int?.
Excerpt from Platform Types in Kotlin :
Besides explicitly specifying a type as optional (e.g. Person?), Kotlin presents us with another beast, called Platform Type, specified by putting a single exclamation mark instead (e.g. Person!). This concept has been created for compatibility reasons, when accessing code from null-unsafe platforms like Java. It is often the case that when using a Java library, many methods return SomeType!, since the Kotlin compiler cannot infer if the result is nullable or not.
For example:
(Mutable)Collection<T>!
Just means the following: "Java collection of T may be mutable or not, may be nullable or not".
Hope this helps.
static setItem(key: string, value: string, callback?: ?(error: ?Error) => void)
This is the declaration of setitem in AsyncStorage. the third parameter is a callback. Could some one explain the use of question marks here. I am familiar with how to use promise but couldn't get a handle of question mark.
AsyncStorage uses flow - Facebook's open-sourced static type checker. You will find #flow at the beginning of the file and it marks flow-enabled source. Flow does a lot of checking on the variable types (including automated type inference) but it also lets you specify the types for variables and parameters. In the example above 'key: string' for example indicates that key should be string type (it's not a valid javascript construct - you cannot specify type in javascript). React has built in transformers that transform it to pure javascript (so all the types are stripped) but before that flow checks if types are passed around properly and find things like passing null or undefined and using it later as object and many other checks. You can read the specs in http://flowtype.org/.
So answering your detailed questionmark question:
'?Error' indicates that error parameter is a "Maybe" type - i.e. it CAN be null and flow will not complain if null or undefined is passed here elsewhere in the code callback (http://flowtype.org/docs/nullable-types.html#type-annotating-null)
'callback?' indicates an optional parameter - so it might be skipped http://flowtype.org/docs/functions.html#function-based-type-annotations
'?(error...)' is another "Maybe" type - it simply indicates that the callback function might take one parameter ('error') or no parameters at all.
When I wrote some general programming utility code, I found that it's good to have both inplace mutator and new object creator member function for one functionality.
For example, some class which represents path in file system may have "normalize" functionality. Path object may mutates itself into normalized one, or returns new normalized path object.
class path {
...
void normalize_itself()
path get_new_normalized_path()
...
}
I've tried some convention for this one, but most of them are not satisfiable.
'normalize!' for inplace function like ruby - good, but most other languages don't support special character to be included in identifier.
'normalize_ip' for inplace function - since most of my function usages are inplace, I think it's too ugly.
'get_normalized' for non-inplace function - acceptable, but can be confused with other simple getter function for member.
'normalized' for non-inplace function - sometime not uniform, and easily confused with its inplace counter part.
write non-inplace function as free function - lack of intellisense assistance of IDE, sometime visibility issues.
I'd like to find some good/practical convention to distinguish two function.
I think normalize for your mutator and grab_normalized for your object creator would work.
What happened to me while programming in Java:
String str
// want to call something(), but signature does not match
something(Foo foo)
// but I have this conversion function
Foo fooFrom(String)
// Obviously I am about to create another method overload.. sigh
something(String s) {
something(fooFrom(s));
}
But then I thought of the possibility of a "automatic type conversion" which just uses my defined conversion function fooFrom everytime a string is passed in where a Foo object is excepted.
My search brought me to the wikipedia page about type conversion with this Eiffel example:
class STRING_8
…
create
make_from_cil
…
convert
make_from_cil ({SYSTEM_STRING})
to_cil: {SYSTEM_STRING}
…
The methods after convert are called automatically if a STRING_8 is used as a SYSTEM_STRING and vice-versa.
Somehow surprising for me I could not find any other language supporting this.
So my question: are there any other languages supporting this feature?
If not, are there any reasons for that, since it seems quite useful to me?
Further I think it would not be difficult to implement it as a language add-on.
There is one minor point that may make the things a bit more complicated. At the moment Eiffel has a rule that conversion can be applied only when the source of reattachment is attached to an object, i.e. is not Void (not null in Java/C#).
Let's look at the original example:
something (str);
Suppose that str is null. Do we get a NullPointerException / InvalidArgumentException, because the code is transformed into
something (fooFrom (str));
and fooFrom does not expect null? Or is the compiler smart enough to transform this into
if (str == null)
something (null);
else
something (fooFrom (str));
?
The current Eiffel standard makes sure that such issues simply do not happen and str is not null if conversion is involved. However many other languages like Java or C# do not guarantee that and the additional complexity may be not worth the effort for them.
I believe that Eiffel is not the only language to support conversion routines, but I would say that it might be one of the very few that integrate this very nicely with the rest of the language definition.
In .NET, for example, you have both op_Explicit and op_Implicit routines that can be used for conversion for languages that support them. And I believe C# does.
Manu
Type coercion (implicit conversion) is a curse and a blessing--handy in some case, but it can also backfire.
For instance, Javascript has many weird coercion rules, that can leads to bug when coercings string to number, etc.
Scala has something called "implicit" which achieves something similar (at least to me) to what you describe in Eiffel. With little surprise, they can lead to certain gotchas. But they can be also very handy, see for instance the article Pimp My Library.
C++ has copy constructors and assignment operator.