Create better documentation and project page.

I'm trying to evaluate this module. But with the current documentation this is difficult. And others are struggling too:
#2007674: Is it possible that the image will be adaptive only from certain break point?
#2024767: I haven't been able to get this to work with Firefox or any Explorer browser with Views Slideshow

Missing information:
What should be entered at 'Resolution' in Adaptive image style setting? The breakpoint above which this image style is used or below? Or is there a different relation between 'Adaptive' and the style it is used in?
What is the purpose of adding multiple breakpoints as the default value is?

Would love to have some documentation for this module.
I don't really understand what this module does except that it will add a class to the image. I know I can use that "adaptive-image" class to add a media query to it and add my withs, but what's the point adding the width size of the preferred screen resolution in the Adaptive effect (UI) if the class is always there at the image?

Can I second the request for testing documentation? I'd really like to know how to be able to check that this is working, without needing to use a different machine. Simply resizing the window isn't enough to do this (and I can see that this is probably intentional), but I can't find any browser functionality that will let me spoof a screensize. Editing the cookies sometimes works a bit, but there's got to be a better way.

Thanks for a nice module!

Agreed--this could be a useful module, with just a paragraph or two of documentation of how to set it up and how to test it. The project page and readme are misleading because it seems to say all you need to do is enable the module and configure the display field. But it seems the module does nothing but slow down your site, so there must be missing setup steps that need to be followed. Please solve the mystery! Thank you.

clarifications

For future doc these are some ideas. They may be not 100% correct, going from my impression of using this module.

Adaptive Image Breakpoints:
Say you have and image width 680px which you what to render at 480px for the iphone. You add the style "Adaptive" to that image style and then specify breakpoints 480px and 680px. This way 480px is rendered for devices with window width of 480px. All other devices get the 680px variant.

The "Window width" is delivered in a cookie from the client.

  //$js = "document.cookie = 'adaptive_image=' + Math.max(screen.width, screen.height) + '; path=/';";
  $js = "document.cookie = 'adaptive_image=' + Math.max(window.innerWidth, window.innerHeight) + '; path=/';";
  

You may need to change the "kind" of width returned (as shown above). Code is in adaptive_image.module, function adaptive_image_init().

Control e.g. in the Picture module is more fine grained - you can map a screen resolution to a responsive image style and specify which resolution the images should then have.

e.g. Screen Res 1200px -> Picture style -> Image 800px.

With Adaptive Image you can only map (AFAICT) Screen Res to Image Res directly. e.g. if screen res. is 1200px and you have a 1200px breakpoint, the image will be generated with 1200px. Not ideal.

In this case setting a breakpoint for 680px as above - for the biggest adaptive image ensures that this 680px image will be served, in the case as described, at anything above 480px. The maximum width will be 680px.

The logic is that say the real screen res. is 580px. Adaptive Image will attempt to find a breakpoint to match. It only has 480px or 680px so will use 680px.

It's important to note that (again AFAICT) on the first access to the image, the full size image (original style without Adaptation) will be served. This is from looking, briefly, at the code in adaptive_image.module.

      if (isset($derivative_uri) && file_exists(str_replace($base_url, '.', $derivative_uri))) {
       	// Deliver existing path to bypass menu callback
        $variables['path'] = $derivative_uri;
      }
      else {
       // Reconstruct the image path to %/%style_name/adaptive-image/% to
        // trigger image generation or file access check
        $variables['path'] = str_replace('styles/' . $variables['style_name'], 'styles/' . $variables['style_name'] . '/adaptive-image', $variables['path']);
      }