Android Tutorial [java] Auto generate library documentation with xml2bb

[warwound]

Library reference generator

This isn't so much a tutorial but i'll post it here anyway...

Have you spent ages laboriously adding javadoc comments to your B4A libraries and then, when you are ready to publish the library and create a new forum thread, find you have to either copy/paste and modify all those javadoc comments to create some documentation in the new thread OR you simply do not bother and leave the library user to figure things out themselves?

Try my xml2bb script.

Copy n paste a library's XML file into the textarea and hit Submit and my script will generate some nicely formatted BB code ready for you to copy into your new thread.

Got a thread where a library has been updated many times and the documentation is fragmented over many pages?
No probs - just generate some new BB code and keep all that documentation in a single post!

I've just updated my YouTubeStreamFinder and Geocoder library documentation if you want to see the format of BB code produced.

All classes, methods, properties, events and permissions are sorted by the script and a bit of color added.

If anyone shows interest i'll add some formatting options - so you can customise it's output.

Martin.

 

[Erel]

Looks very nice!

 

[pluton]

Excellent warwound

This will short time to anyone who made the library and wan't to post here in forum.
Nice job

 

[warwound]

Excellent warwound

This will short time to anyone who made the library and wan't to post here in forum.
Nice job

As i mentioned:

If anyone shows interest i'll add some formatting options - so you can customise it's output.

If anyone is gonna use it i'll update and make it a bit more customisable.


Martin.

 

[XverhelstX]

I'll use it

Tomas

 

[vb1992]

:sign0098:

 

[Erel]

Now that Tomas use it with the PayPal library I realize that this is really a great tool. I will make it a "sticky" thread.

 

[warwound]

I've been looking at some library xml generated by other users' libraries and see some have a root comment element.

My library xml:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <doclet-version-NOT-library-version>1.02</doclet-version-NOT-library-version>

    <!-- classes removed --> 

    <version>1.3</version>
    <author>Martin Pearman</author>
</root>

AHQuickAction.xml:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <doclet-version-NOT-library-version>1.02</doclet-version-NOT-library-version>

    <!-- classes removed --> 
    <version>1.0</version>
    <comment>Where in the library source code do you put the comment that ends up here?</comment>
    <author>Markus Stipp</author>
</root>

Where in the library source code do you put the comment that generates this root comment element?

My WebViewExtras has this comment:

@ActivityObject
@Author("Martin Pearman")
@Events(values={"GeolocationPermissionsRequest As Int"})
@ShortName("WebViewExtras")
@Version(1.3F)
/**
 * WebViewExtras exposes some native Android WebView methods to your B4A application.
 */
public class WebViewExtras {
// source removed
}

That comment does not appear in the library XML.

Another question...

I was gonna update xml2bb so users could choose to generate documentation as either a BB list or a BB table.
So i did some tests and it looks as though this forum has not enabled the BB table tag, my sample BB table code displayed as text rather then being rendered as a table:

[table]
[tr][th]title here[/th][/tr]
[tr][td]data here[/td][/tr]
[/table]

Could the BB table tag be enabled so we can better format our posts?
And if that's possible can both BB th and td tags be enabled instead of just BB td tag?
(It seems as if some sites have BB table and BB td enabled but not BB th - it must be configurable to enable all or some BB tags?).

Thanks.

Martin.

 

[Erel]

Library level documentation is done by adding a special method:

   /**
    * The HTTP library allows you to communicate with web services and to download resources from the web.
    *As network communication can be slow and fragile this library handles the requests and responses in the background and raises events when a task is ready.
    */
   public static void LIBRARY_DOC() {
      //
   }

All the BB codes are enabled. Maybe this version of vbulletin doesn't support those codes.

 

[warwound]

All the BB codes are enabled. Maybe this version of vbulletin doesn't support those codes.

I found the reference page: Android Development Forum - Basic4android - vB Code List

No sign of the table tag being enabled so i'll stick to using a list.

Martin.

 

[warwound]

Library reference generator

xml2bb updated, now named the Basic4Android library reference generator

This update fixes many minor formatting bugs, adds support for library xml Author, Comment, Field and Version tags and allows you to create HTML as well as BBCode library reference.

BBCode output is styled as with the previous version - no changes to be seen there except the extra tags being included.

HTML output is a feature i've wanted to add to the script for a while, you can see a sample HTML reference page here: OSMDroid.
The sample page is all 'nicely' styled, if you remove the page's CSS style rules you'll get plain HTML.

URL to the script is the same as before: B4A library reference generator

If any of you use this script and would like to customise it's ouput - whether you want to change the order of output elements, change styles or whatever - you are welcome to request a copy of the source code so that you can create your own uniquely styled reference pages.

Martin.

 

[XverhelstX]

Awesome!
Perfect output, I like it!

Tomas

 

[warwound]

Basic4Android library reference generator updated to the Basic4Android library and module reference generator.

This updates adds basic support for creating reference documentation from module files - .b4a and .bas files.
This code example shows how the script recognises comments to be used in the reference document:

' Any comment immediately before Sub Process_Globals is treated as the main module comment.
Sub Process_Globals
   'These global variables will be declared once when the application starts.
   'These variables can be accessed from all modules.

End Sub

'   A comment that is not immediately followed by a Sub is ignored

Sub Globals
   'These global variables will be redeclared each time the activity is created.
   'These variables can only be accessed from this module.

End Sub

Sub Activity_Create(FirstTime As Boolean)
   'Do not forget to load the layout file created with the visual designer. For example:
   'Activity.LoadLayout("Layout1")

End Sub

Sub Activity_Resume
   ' all comments within Subs are ignored
End Sub

   ' called when the activity is paused
Sub Activity_Pause (UserClosed As Boolean)

End Sub

'   this comment will be ignored

'   GetSquare accepts an Int parameter and returns an Int value.
'   The returned value is the parameter passed to the Sub squared
Sub GetSquare(Number As Int) As Int
   Return Number*Number
End Sub

'   Multiline comments are parsed
'   This is line 2 of a multiline comment
'   And this is line 3.
Sub DoNothing
   '   this Sub does nothing and this comment will be ignored
End Sub

As with library reference, you can select BBCode or HTML output.
Here's the BBCode created from the above example(the example was saved as test.bas hence the module name is 'test'):

test
Any comment immediately before Sub Process_Globals is treated as the main module comment.

• Activity_Pause (UserClosed As Boolean)
  called when the activity is paused
• DoNothing
  Multiline comments are parsed
  This is line 2 of a multiline comment
  And this is line 3.
• GetSquare (Number As Int) As Int
  GetSquare accepts an Int parameter and returns an Int value.
  The returned value is the parameter passed to the Sub squared

URL to the script is the same as before: B4A library and module reference generator

Martin.

 

[warwound]

The xml2bb tool is going to be temporarily offline.
I'm changing webhosts and until the new DNS settings take effect it's likely that links to xml2bb will fail.

Once the new webhosting is set up i'll update this post with links to the new location.

Martin.

 

[warwound]

xml2bb is now back online.
It has a new URL, so update your bookmarks:

http://b4a.martinpearman.co.uk/xml2bb/

Martin.

 

[thedesolatesoul]

Hi Martin,
It seems if I declared a sub as

Public Sub Initialize(Interval As Int, BufferSize As Int, Module As Object  ,EventName As String)

the tool doesnt generate bbcode for it, but if I drop the 'public', then it does?

 

[warwound]

The code that generates documentation for code modules dates back to before when classes were introduced in b4a i think.
And i never updated it to support classes.

If i have time later i'll take a look and see what work is involved to support classes - maybe i'll even have time to fix an outstanding bug where event signatures that return a value are not correctly handled...

Martin.

 

[thedesolatesoul]

Ah I see.
Thanks!

 

[tchart]

Warwound, thanks for your tool. I found it throws an error if there is an apostrophe in the comments (eg doesn't).

This is the error I get;

An error occurred while trying generate the BB code: String could not be parsed as XML

 

[Erel]

Try to write ' instead of '