Android Tutorial Core Documentation [UNOFFICIAL]

As a Development Team Leader, I like my code to be "just so". I also like my documentation to be "just so".
I am humble enough to know that I don't know everything, but I do know what I like. I am definitely a stickler for certain things to be done a certain way.

So when I found this great site and application (yes, I am talking about b4A), I was really excited and wanted to read the documentation so I knew where and how to work with it.

NOTE: What I say in the following paragraphs about fellow forum members efforts is not meant to be overly-critical. I understand that we are all doing this for love, and I am just trying to be honest. Please don't take anything to heart - it is meant to be constructive.

I found the beginners guide useful, and the Getting started guide ok, but when I found the seperate Core guide, I didn't think it was good enough.
Ok sure, the information is there (mostly), but was it consistent?
If asked, I would have to say no.

So, I can do one of three things:
1. Put up with it
2. Complain about it
3. Fix it

I decided that #3 was better for me and the B4A community.

So, accordingly, I am writing documentation that can be used by everyone, not just me.
I believe the following benefits will be realised with this documentation:
1. Consistency. Each keyword will get equal billing and will be documented the same as the next. This means...
2. Examples. Each keyword get's it's own example.
3. Colour coding. I will follow the B4A colour coding standard.
4. Grammar. As a native English speaker, I do not have to overly process the information I have available to me, and try and think differently before I put pen to paper.

There will be downsides to this approach.
1. Timeliness. I have no affiliation with Erel and Anywhere Software, and I am not a Beta tester, so I don't get early access to changes. This means there will be a lag between product releases and documentation updates.
2. Descriptions will differ. I won't always agree with the description offered in the official information, and so what you see in the IDE's intellisense popup window, may not 100% correspond to my version. The overall message will be the same, but the words may be different.

Here is the format I have come up with...

Abs

Description
Returns the absolute value of a double-precision floating-point number.

Syntax
Abs(Value As Double) As Double

Parameters
Value
Type: Double

Return Value
Double

Remarks
The absolute value of a Double is its numeric value without its sign. For example, the absolute value of both -123.45 and 123.45 is 123.45.

Example
Dim Value As Double
Dim Result As Double

Value = -123.45

Result = Abs(Value)

' Result will equal 123.45

See Also

On top of this, I would like to confer further with Erel to understand what version of B4A received particular Keywords, (or changes, which should be VERY limited or non-existant), and this can also be shown. This will allow those of us that are not using the most recent version to know what is (and is not) available to them.

Attached is a DRAFT/ALPHA version of my document. I will update this thread as I require to get the final version released. Right now it is in Word's Docx format, but that will change to a PDF when I get closer to Release 1.0 (which will actually be release 2.50, following the B4A version numbering).

Enjoy!

Update:
v0.2 added as a pdf
The file is also hosted elsewhere because of the Forum upload size-limits.
Link: http://sdrv.ms/ViZNVE

 

[fdx12345]

Great!!!!!!!!

Great Start. Now to do all of the core libraries the same way. Personally, I am great at this kind of thing. I wish I could make a living doing it. In the US, I feel engineers in general are excellent at design, building and code but are terrible at documentation. Their documentation looks fine to them, but then they use it all of the time.

Just as a note: B4A documentation is not as bad as many I have seen and the program itself is a blessing when it comes to android application development. It takes out a lot of the detail work (like missing with xml files directly) and allows the user to spend more time developing their applicaiton.

 

[Vader]

Great Start. Now to do all of the core libraries the same way.

Yes, I was thinking the same thing, but it would be a little presumptuous of me to take on that role right now. I'll walk before I try to run. Thanks for the comment.

 

[Erel]

Thank you for sharing this. :sign0098:

 

[Merlot2309]

Wowwww - compliments.

I can and will certainly use this documentation.
Thank you for taking the time and effort to create this and I'm looking forward to see more.

Regards,
Helen.

 

[MLDev]

Thanks Vader! :sign0098:

 

[JonPM]

Awesome, thanks! Will be using this

 

[Vader]

More info

Ok, so I have added a basic skeleton for the core libraries, making the document 312 pages in length.

I will not be making this version public until it is in a more usable state.

This document is now (just) the longest one I have ever put together. We will just have to wait and see if it will be broken down. If it gets unmanageable, that's what I will have to do.

Dave

 

[Stulish]

Vader, first off great work, secondly i love the list of key words some of my time is spent looking for the specific word (i know what it was in VB) and there is a slight change in B4A. There is a section on VB->B4A in the forum, but i think this will be useful to have in my back pocket.

Thanks again

Stu

 

[Vader]

In my search for information, I have come across the Core Library list in the Wiki.

This list was unsorted. It is now sorted alphabetically.

Libraries - Basic4android Wiki

EDIT: All libraries on this page are now sorted alphabetically. In the case of external/third party libraries, the sort order is within the Author's list.

 

[Jost aus Soest]

+1

Great start!

 

[jeeradate]

Thank you very much. :sign0142:

 

[Roger Garstang]

Very cool. Only suggestions I have is more links like you have in the ToC. This will help to make it very manageable when larger and grouping too. So, in places like See Also or even in examples when you click those keywords it jumps to that description. Maybe even a page for Return Types/Variable Types that lists Size, Range, Limitations, an Equates Page, etc. Then when they click on Double or String return types it jumps to that page.

I came here from PowerBASIC and they had one of the best help files I had to use. It was all in one .chm file and upon opening it has a main page with links to an Alphabetical list of Commands, Variable Types, Numeric Equates, String Equates, Introduction, etc. A PDF which I'm guessing is made from a Word Document may be difficult to do all of this since I believe the CHM file is nothing more than a bunch of web pages that make linking much easier, but just having the pages link off of the Title Page will be great. All the extra linking can be added later.

I do have a copy of a help file creator a company was giving away years ago then had a server crash so never updated it further. It may be helpful for this too.

 

[TestMyChess]

Applause

Well done and thank you very much for doing this.

 

[JTmartins]

Thanks

What can I say ?

Thank you very much.

José

 

[Vader]

Here is a link to a thread describing a tool I am developing to assist with documentation:

B4A Library Document Loader

If you subscribe to that thread also, you will be able to receive posts when I update it.

 

[c regis]

More... arms to help documentation.. Nice..!

I wish good luck for his brilliant work will be very important especially for new users.
We know you have many talents but sometimes lacking in help.
Force..Vader

 

[ADPTraining]

Good stuff Vader

Great stuff, thanks for your time and dedication...

 

[Vader]

I thought I should just update you all and let you know my progress on this.

I used some undocumented features in the B4a Object Browser to help me build a documentation framework. This framework has the current information from the XML files across all standard libraries.

The information is ok, but not formatted. It is also there in all it's glory with spelling and grammar mistakes.

I am now going through and formatting it and applying styles. Once that is done I will get examples for all keywords.

The bad news is that this is a big job. Well, to be honest, it is a huge job. I am up to about page 500, with just over 1000 pages remaining.
Yes, you read correctly - over 1500 pages.

I should also let you know that the plan is to release this as a fully-fledged printed reference guide/manual. The electronic version will be available to everyone that buys the book.

The format will be as per the early threads in this post, so hopefully everyone likes what I came up with.

Sorry, but I can't offer this book freely - it is just going to take too much of my time to put it together to a quality standard that I will be happy with.

If you don't want to buy it, you don't have to. If you do, when it's finished, then you will have the opportunity to. It will be a limited run to start with, and I will have to take orders to get an idea of numbers.

I just thought you should know...

 

[jeeradate]

My eye is not good for hard copy, I don't have room to store hard copy which will obsolete very soon and hard to update.

But I prefer to have only electronic one that searchable or the website that I can pay for membership. Then you and members can update it as this technology is fast growing.

It is good to have the place that we can look up for everything in the well organized

I willing to pay for online document if the price is reasonable.

:wav: