How can I integrate Javadoc into a Xamarin Java Binding library?

Question

I have read Xamarin's documentation on this and also noted the discussions on the Xamarin Forums. Either Something's missing or I have missed something because none of this works in my case, which is:

My environment is OSX. I have an AAR created in Java and need to provide this as a DLL for Xamarin devs to use. I have created a Java Binding Library in Xamarin Studio which produces a DLL but my parameters are munged (e.g p0 etc). I could endlessly map each parameter in Metadata.xml but ... say it 'aint so! I want to use my JavaDoc to do the heavy lifting and changed the .csproj as indicated in Xamarin's documentation by adding:

...     
<PropertyGroup>
   <Java7DocPaths>JavaDocs\myLib</Java7DocPaths>
</PropertyGroup>
..

My JavaDocs are in sibling folder to the .csproj file (the myLib subfolder is just not shown here):

I clean and rebuild the Java Binding project and, to my disappointment, munged parameter names despite my efforts. How do you get this to work using Xamarin Studio on OSX?

Thanks SushiHangover. I have run xbuild with /verbosity: debug that gives no errors and no warnings. When I use /verbosity:diagnostic it outputs JavaDocs: {0} for the JarToXml task, I'm exploring what could cause that.

Run through my answer and if you are getting something other than the warning J2X8001, update your question and I take a look.... — SushiHangover

SushiHangover SushiHangover · Accepted Answer · 2016-05-26T02:27:41

You did not specify which warning the JARTOXML task of the ExportJarToXml Target is producing. If you do not know it:

cd {YourJavaBindingLibraryDirectory}
rm -Rf bin obj # Remove build artifacts so all tasks all executed
xbuild /verbosity:debug # /verbosity:diagnostic if needed

Note: Try using verbosity:diagnostic if you do not see any warning produced...

Search the output for the JARTOXML task...

The number one issue that I see is:

J2X8001

JARTOXML:  warning J2X8001: Couldn't access javadocs at specified docpath.  Continuing without it...

FYI: This example uses bluejamesbond/TextJustify-Android, a fantastic Text justification library ;-)

First, double check the relationship of JavaDocPaths in your .csproj:

.csproj contains:

<PropertyGroup>
  <JavaDocPaths>JavaDocs/textjustify-android-2.1.6-javadoc</JavaDocPaths>
</PropertyGroup>

Equals Project dir:

TextJustifyAndroid.csproj
~~~~
├── JavaDocs
│   ├── textjustify-android-2.1.6-javadoc
~~~~

Note: This is relative to the binding project .csproj location, not the solution.

Next, make sure that you have expanded the JavaDoc jar and it is in its original structure.

Here is how I personally structure the project tree:

├── Jars
│   └── textjustify-android-2.1.6.aar
├── JavaDocs
│   └── textjustify-android-2.1.6-javadoc.jar

I copy the *.javadoc.jar(s) in the my JavaDocs subdirectory, I then expand them (I use unzip, but any tool that preserves the dir structure is fine)

unzip textjustify-android-2.1.6-javadoc.jar -d textjustify-android-2.1.6-javadoc

This results in:

├── Jars
│   └── textjustify-android-2.1.6.aar
├── JavaDocs
│   ├── textjustify-android-2.1.6-javadoc
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   ├── allclasses-frame.html
│   │   ├── allclasses-noframe.html
│   │   ├── com
│   │   │   └── bluejamesbond
│   │   │       └── text
│   │   ├── script.js
│  ~~~~~~~~~~~~~~~~~~~~~~~~
│   │   ├── serialized-form.html
│   │   └── stylesheet.css
│   └── textjustify-android-2.1.6-javadoc.jar

FYI: I preserve the version in the directory name to aid in versioning as I might be working with multiple versions of the same .aar|.jar within the same project... but you can rename it, just make sure it matches what is in your .csproj.

Running xbuild /verbosity:debug should result in the ExportJarToXml target producing no warning:

~~~~
Target ExportJarToXml:
        Tool /usr/bin/java execution started with arguments: -XX:-UseSplitVerifier -jar /Library/Frameworks/Xamarin.Android.framework/Versions/Current/lib/mandroid/jar2xml.jar --jar=.../Justify/TextJustifyAndroid/obj/Debug/library_project_jars/classes.jar --ref=/Users/sushi/Library/Developer/Xamarin/android-sdk-macosx/platforms/android-22/android.jar --out=.../Justify/TextJustifyAndroid/obj/Debug/api.xml --javadocpath=.../Justify/TextJustifyAndroid/JavaDocs/textjustify-android-2.1.6-javadoc
~~~~

How can I integrate Javadoc into a Xamarin Java Binding library?

1 Answers

J2X8001