Incomplete Documentation!

[Dimitar Bonev]

Hello, Google Maps developers

I usually don't complain about documentation especially when it is official one from Google, but in a single weekend I have been filled up with enough misleading/confusing/incomplete documentation and examples:

            1.google.maps.Map, google.maps.MapOptions

When I'm newcomer   to a technology/product I usually start with the minimum code/configuration and then add up  to it and watch the effect of every step that I make. So I call the map constructor witch has only one required parameter - mapDiv:Node. But nothing meaningful happens - just some background color that I barely distinguished it from the browser's default so I knew that the id of the node is is not mistyped . If I try to zoom in or out the following error is printed in js console:  

1. Chrome: Uncaught RangeError: Maximum call stack size exceeded
   

1. main.js:30 Chrome: Uncaught TypeError: Cannot call method 'lng' of null FF: too much recursion
   
   (BTW in general FF messages give more information to me than those of Chrome, for example FF prints 'someObject is null' , but in Chrome I see 'cannot call method "myMethod" of null'. And when I have 10 instances that have a common parent with method "myMethod", guess which of these 10 is actually null. It's similar case with Syntax errors ) 
   
   

So I expect to see a world map with zoom:0 and default map type like Satellite, because they are not required, but no - single-color background and js errors. So what was wrong - when I went back to the examples I noticed that MapOptions was virtually used everywhere. But I've noticed that even the first example was inconsistent with the API Reference - initializing only two of the three required properties to MapOptions and later setting the third required property on the Map object itself. So I made the assumption that while MapOptions is optional in the Map constructor,  these three required properties are required for the Map itself and not for MapOptions and I can set them just by calling the appropriate methods of Map instance and I turned right with this assumption:

map = new google.maps.Map(map_wrapper);

map.setMapTypeId(google.maps.MapTypeId.HYBRID);

map.setCenter(new google.maps.LatLng(40.69847032728747, -73.9514422416687));

map.setZoom(0);

The above code works just fine without MapOptions, but can be combined like setting any of the three in MapOptions and later setting the rest on the map instance itself. But this was not reflected in the API Reference - it states three required properties for MapOptions and one required parameter for Map and thats it, but in my opinion these should be the other way around - MapOptions properties should be optional and these three should be stated as required in the Map class specification, irrelevant how do they get to the map - either by MapOptions or by Map methods or any other way.

2. Region Parameter

Here is a spreadsheet that I've made based on the documentation of respective APIs:

Region Parameter Accepted Values

Let's play a game - it's called "Fill in the Blanks". So we have three related APIs that accept different set of values for Region parameter.

Maps API accepts Unicode region subtag identifiers, later found out that these are based on IANA language region subtag. So IANA states that GB is the region subtag for United Kingdom and the example in Maps API Doc. is consistent with that.

Type: region
Subtag: GB
Description: United Kingdom
Added: 2005-10-16

Geocoding API accepts ccTLD.

Client Geocoder is very confusing for me - it accepts  IANA language region subtag. 
"

 In most cases, these tags map directly to familiar ccTLD ("top-level domain") two-character values such as "uk" in "co.uk" for example." - Why do you give example with "uk" for ccTLD that a tag maps directly to it? The region subtag identifier for United Kingdom is GB instead of UK.
" 

 In some cases, the region tag also supports ISO-3166-1 codes, which sometimes differ from ccTLD values ("GB" for "Great Britain" for example)." - Inappropriate example again. Why do you mention GB as supported code, it is in the list of accepted region tag identifiers that you accept. Also witch are these "some cases"?

Also in all of the aforementioned APIs' documentation  ISO-3166-1 is included and an example of GB code and UK ccTLD to note that they don't match. Does this mean that I can use GB and UK interchangeably or what? If you have used an examples with how to region localize an API for United Kingdom it would be way more clear - there is an example only in Maps API Docs.

I should suggest you to be more consistent and more unambiguous  in the documentation you provide - for example having one simple spreadsheet list of accepted values and called it Google APIs Region Parameter Accepted Values or something like that and as an extra it will play a role of an interface without tying it to specific implementation :), just one simple link to one simple list and that's it, not some big file of which you use only part of it like the IANA file case.

3. BONUSES (Not related to Maps API directly)

3.1. So I want to use Fusion Tables with Google Maps and I went to examine the java sample code. The line with code 

scanner.findWithinHorizon(CSV_VALUE_PATTERN, 0);

       doesn't tell me what it does. I have used Scanner before, but never called a method with "Horizon" within its name, and what the word           "Horizon" means in context of Scanner (I am non-native English speaker as you can see) - was it something similar to a line?. And this literal argument '0' shouldn't be literal for expressiveness of code - does this argument mean "from the start of the Horizon"? So I open the java 6 Scanner javadocs and guess what - this horizon parameter is not in the list of Parameter descriptions for that method, but thank God - it is described in the general usage explanation for the method. But if you read carefully the javadoc for

public String findWithinHorizon(String pattern,
                                int horizon)

you will find a mistype - findWithinHorizon(Pattern.compile(pattern, horizon)). I thing the author wanted to write findWithinHorizon(Pattern.compile(pattern), horizon). I guess that this horizon parameter isn't foreign to me only :)

3.2. Google groups (I'm using Google Chrome 13 stable) 

I was having really hard time struggling with text formatting while writing this post. I started with Numbered list formatting, but at some point I couldn't get the next number - neither Enter, nor ( Shift+)Tab helped me, so I just started numbering the paragraphs myself. 

Text from clipboard is pasted formatted - but why would I want the text that I write after the pasted one to have the same formatting and blend whit it? Is this some utility tool for plagiarizing?

Double Quotes - if I have two adjacent lines and the second one starts with double quote, when I press Enter at the end of the first line the double quote stays on the newly inserted second line while the text is pushed down to the third line.

Indentation is hard to manage here - sometimes I cannot remove it with Delete, Backspace, Increase (Decrease) Indentation... It just stays there.

I have a strange drop-down list for choosing a language and a button with name "Always use this language", but I cannot click on any of these, It's just like they aren't there except one thing - they take portion of the height of the screen so Google Groups is really unpleasant to browse for Topics, it's like I'm seeing only two-three topic titles at one screen, this means more scrolling than usual :)

Thank you for your patience! Feel free to leave a comment!

[Rossko]

> When I'm newcomer   to a technology/product I usually start with the minimum
> code/configuration and then add up  to it and watch the effect of every step
> that I make. So I call the map constructor witch has only one required
> parameter - mapDiv:Node. But nothing meaningful happens - just some
> background color that I barely distinguished it from the browser's default
> so I knew that the id of the node is is not mistyped

This all seems to covered in Documentation - Tutorial
http://code.google.com/apis/maps/documentation/javascript/tutorial.html

> So I expect to see a world map with zoom:0 and default map type like
> Satellite, because they are not required, but no - single-color background
> and js errors. So what was wrong

The expectation, I think

> - when I went back to the examples I
> noticed that MapOptions was virtually used everywhere. But I've noticed that
> even the first example was inconsistent with the API Reference -
> initializing only two of the three required properties to MapOptions and

Which example?

[Dimitar Bonev]

That example  

  var myOptions = {
    zoom: 6,
    mapTypeId: google.maps.MapTypeId.ROADMAP
  };

   google.maps.MapOptions object specification

center

LatLng

The initial Map center. Required.

mapTypeId

MapTypeId

The initial Map mapTypeId. Required.

zoom

number

The initial Map zoom level. Required.

[Andrew Leach]

On 8 August 2011 22:53, Dimitar Bonev <dsb...@gmail.com> wrote:

That example   

http://code.google.com/apis/maps/documentation/javascript/basics.html#Geolocation

That seems fine to me. The three properties of the map (centre, zoom and mapTypeId) are set before it's used and anything else happens. Two are set in the MapOptions object; that example is how to use something else to set the map centre. You do need to ensure that the map is completely defined before attempting to do anything else (like zoom, or place a marker...) but it doesn't really matter how you do that.

And as you see at http://code.google.com/apis/maps/documentation/javascript/examples/map-geolocation.html it works, so that code must be right.

[Dimitar Bonev]

I think you're missing the point here. I'll try to explain it within one sentence, because it seems the text I've made specifically bold and italic in my second post is hard to be noticed :). The Google Maps API Reference states that MapOptions should be constructed by providing three "required" properties, but in the example only two are provided and in my first post I've pointed out that it could be easily used with any number of properties.

P.S. Mr Leach, I have no idea why you thought that I had wanted to say the example is wrong or it doesn't work. I think the example is excellent, it's just inconsistent with the API Reference. So either the example or the Reference should be refactored and if I had to pick which one I would say the Reference - why those MapOptions properties are listed as required anyway.

[Chris Broadfoot]

Hi Dimitar,

The docs are correct, albeit I admit a little confusing.  There are three (well, three-and-a-half, kinda) ways to initialise a map:

1) new google.maps.Map(div, { center: ..., zoom: ..., mapTypeId: ... })

2) new google.maps.Map(div).setOptions({ center: ..., zoom: ..., mapTypeId: ... })

3) new google.maps.Map(div); map.setCenter(...); map.setZoom(...); map.setMapTypeId(...);

3a) new google.maps.Map(div); map.setMapTypeId(...); map.fitBounds(...);

MapOptions (the second parameter to the Map constructor) *is* optional -- there are other ways to initialise the map.

Hope that helps clarify things,

Chris

--

http://twitter.com/broady

On Tue, Aug 9, 2011 at 6:57 PM, Dimitar Bonev <dsb...@gmail.com> wrote:

I think you're missing the point here. I'll try to explain it within one sentence, because it seems the text I've made specifically bold and italic in my second post is hard to be noticed :). The Google Maps API Reference states that MapOptions should be constructed by providing three "required" properties, but in the example only two are provided and in my first post I've pointed out that it could be easily used with any number of properties.

P.S. Mr Leach, I have no idea why you thought that I had wanted to say the example is wrong or it doesn't work. I think the example is excellent, it's just inconsistent with the API Reference. So either the example or the Reference should be refactored and if I had to pick which one I would say the Reference - why those MapOptions properties are listed as required anyway.

--
You received this message because you are subscribed to the Google Groups "Google Maps JavaScript API v3" group.

To view this discussion on the web visit https://groups.google.com/d/msg/google-maps-js-api-v3/-/rW8sg4UZV1cJ.

To post to this group, send email to google-map...@googlegroups.com.
To unsubscribe from this group, send email to google-maps-js-a...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/google-maps-js-api-v3?hl=en.