While jonp is right on that we'd need doc improvements, there is some
public draft documentation that mentions these attributes:
http://docs.xamarin.com/android/Releases/Mono_For_Android_4/Mono_for_Android_4.1.0#Draft_Documentation
Also my troubleshooting doc might be of help:
https://docs.google.com/document/d/11PidPfkc0-Emiz-FntKcH7t_RH___xLVF33BGcc_RGI/edit
If there are still unclear things, please feel free to post questions,
which will improve our documentation effort :-)
Thanks,
Atsushi Eno
Jonathan Pryor wrote:
On May 2, 2012, at 3:45 AM, johnHolmes wrote:
my first attempt to "sanitize" the return type was
<attr
path="/api/package[@name='com.openfeint.internal.vendor.org.codehaus.jackson']/class[@name='JsonNode']/method[@name='getElements']"
name="managedReturn">IEnumerable</attr>
i will try with your suggested code. Just one thing, am I supposed to use
"*managedReturn*" or "*return*" for the *name *attribute?
This is one of those things that we need to provide documentation& guidance
for. :-)
The //method/@return attribute and the //parameter/@type attributes are used to
generate the JNI method signature, and thus it must match what JNI requires (or
the method won't be found). Because Java generics are implemented via Type
Erasure, these two attributes are identical:
return="java.util.Iterator"
return="java.util.Iterator<java.lang.Integer>"
For more on type erasure...go consult a decent Java 5.0 book, or see my
diatribe:
http://www.jprl.com/Blog/archive/development/2007/Aug-31.html
The //method/@managedReturn attribute, if present, overrides the default return type
(normally a PascalCased, .NET-ized version of the Java type name) and replaces it with a
"compatible" managed equivalent.
What's a "compatible" type? Something that is _implicitly_ convertible from the
generated Java type wrapper to the managed type.
The only place we use //method/@managedReturn is to "work around" Java's
support for covariant return types. For example,
android.text.SpannableStringBuilder.append() has a covariant return type and returns
SpannableStringBuilder:
http://developer.android.com/reference/android/text/SpannableStringBuilder.html#append(char)
By default, this would result in a C# method:
public override SpannableStringBuilder Append(char text);
C#, unfortunately, doesn't support covariant return types and wants the return
type to be IAppendable (or `override` to be removed). So we fix it up:
<attr
path="/api/package[@name='android.text']/class[@name='SpannableStringBuilder']/method[@name='append']"
name="managedReturn">Java.Lang.IAppendable</attr>
Which results in the compatible type Java.Lang.IAppendable, which works because
SpannableStringBuilder implements IAppendable. The result:
http://androidapi.xamarin.com/?link=M%3aAndroid.Text.SpannableStringBuilder.Append(System.Char)
As a variation on managedReturn, there's also an //method/@enumReturn attribute
which is used for changing the return type from e.g. `int` to an enum type. We
don't use these internally, opting instead to use Transform Files.
http://docs.xamarin.com/android/tutorials/Binding_a_Java_Library_(.jar)#Transform_Files
The transform files work by generating the //method/@enumReturn attribute,
which our source code generator uses.
- Jon
_______________________________________________
Monodroid mailing list
Monodroid@lists.ximian.com
UNSUBSCRIBE INFORMATION:
http://lists.ximian.com/mailman/listinfo/monodroid
_______________________________________________
Monodroid mailing list
Monodroid@lists.ximian.com
UNSUBSCRIBE INFORMATION:
http://lists.ximian.com/mailman/listinfo/monodroid
