ENH: Additional methods to otbObjectListSource and comments

Code/Common/otbObjectListSource.h

@@ -59,11 +59,108 @@ namespace otb
           typedef typename TOutputList::Pointer OutputListPointer;
   
           typedef itk::DataObject::Pointer DataObjectPointer;
-
+          
+  /** Make a DataObject of the correct type to used as the specified
+           * output.  Every ProcessObject subclass must be able to create a
+           * DataObject that can be used as a specified output. This method
+           * is automatically called when DataObject::DisconnectPipeline() is
+           * called.  DataObject::DisconnectPipeline, disconnects a data object
+           * from being an output of its current source.  When the data object
+           * is disconnected, the ProcessObject needs to construct a replacement
+           * output data object so that the ProcessObject is in a valid state.
+           * So DataObject::DisconnectPipeline eventually calls
+           * ProcessObject::MakeOutput. Note that MakeOutput always returns a
+           * SmartPointer to a DataObject. If a subclass of ImageSource has
+           * multiple outputs of different types, then that class must provide
+   * an implementation of MakeOutput(). */
           virtual DataObjectPointer MakeOutput(unsigned int idx);
+          
+            /** Graft the specified DataObject onto this ProcessObject's output.
+           * This method grabs a handle to the specified DataObject's path
+           * data to use as its output's own path data. It also copies the
+           * region ivars (RequestedRegion, BufferedRegion,
+           * LargestPossibleRegion) and meta-data (Spacing, Origin) from the
+           * specified data object into this filter's output data object. Most
+           * importantly, however, it leaves the Source ivar untouched so the
+           * original pipeline routing is intact. This method is used when a
+           * process object is implemented using a mini-pipeline which is
+   * defined in its GenerateData() method.  The usage is:
+           *
+           * \code
+           *    // setup the mini-pipeline to process the input to this filter
+           *    firstFilterInMiniPipeline->SetInput( this->GetInput() );
+           *
+           *    // setup the mini-pipeline to calculate the correct regions
+           *    // and write to the appropriate bulk data block
+           *    lastFilterInMiniPipeline->GraftOutput( this->GetOutput() );
+           *
+           *    // execute the mini-pipeline
+           *    lastFilterInMiniPipeline->Update();
+           *
+           *    // graft the mini-pipeline output back onto this filter's output.
+           *    // this is needed to get the appropriate regions passed back.
+           *    this->GraftOutput( lastFilterInMiniPipeline->GetOutput() );
+           * \endcode
+           *
+           * For proper pipeline execution, a filter using a mini-pipeline
+           * must implement the GeneratseInputRequestedRegion(),
+           * GenerateOutputRequestedRegion(), GenerateOutputInformation() and
+           * EnlargeOutputRequestedRegion() methods as necessary to reflect
+           * how the mini-pipeline will execute (in other words, the outer
+           * filter's pipeline mechanism must be consistent with what the
+             * mini-pipeline will do). */
           void GraftOutput(itk::DataObject *graft);
+          
+            /** Graft the specified data object onto this ProcessObject's idx'th
+           * output. This is the similar to GraftOutput method except is
+           * allows you specify which output is affected. The specified index
+           * must be a valid output number (less than
+           * ProcessObject::GetNumberOfOutputs()). See the GraftOutput for
+             * general usage information. */
           void GraftNthOutput(unsigned int idx, itk::DataObject *graft);
+          
+            /** Get the output data of this process object.  The output of this
+           * function is not valid until an appropriate Update() method has
+           * been called, either explicitly or implicitly.  Both the filter
+           * itself and the data object have Update() methods, and both
+           * methods update the data.  Here are three ways to use
+           * GetOutput() and make sure the data is valid.  In these
+           * examples, \a image is a pointer to some Image object, and the
+           * particular ProcessObjects involved are filters.  The same
+           * examples apply to non-image (e.g. Mesh) data as well.
+           *
+           * \code
+           *   anotherFilter->SetInput( someFilter->GetOutput() );
+           *   anotherFilter->Update();
+           * \endcode
+           *
+           * In this situation, \a someFilter and \a anotherFilter are said
+           * to constitute a \b pipeline.  
+           *
+           * \code
+           *   image = someFilter->GetOutput();
+           *   image->Update();
+           * \endcode
+           *
+           * \code
+           *   someFilter->Update();
+           *   image = someFilter->GetOutput();
+           * \endcode
+           * (In the above example, the two lines of code can be in
+           * either order.)
+           *
+           * Note that Update() is not called automatically except within a
+           * pipeline as in the first example.  When \b streaming (using a 
+           * StreamingImageFilter) is activated, it may be more efficient to
+           * use a pipeline than to call Update() once for each filter in
+           * turn.
+           *
+           * For an image, the data generated is for the requested
+           * Region, which can be set using ImageBase::SetRequestedRegion().
+           * By default, the largest possible region is requested.
+             */
           OutputListType * GetOutput(void);
+          OutputListType * GetOutput(unsigned int idx);
 
   
         protected:

Code/Common/otbObjectListSource.txx

@@ -35,11 +35,14 @@ namespace otb
   // output must be of type TOutputImage
     typename TOutputList::Pointer output
         = static_cast<TOutputList*>(this->MakeOutput(0).GetPointer()); 
-    this->itk::ProcessObject::SetNumberOfRequiredOutputs(1);
-    this->itk::ProcessObject::SetNthOutput(0, output.GetPointer());
+    this->Superclass::SetNumberOfRequiredOutputs(1);
+    this->Superclass::SetNthOutput(0, output.GetPointer());
   
   }
-
+  
+  /**
+   *
+   */
   template<class TOutputList>
       typename ObjectListSource<TOutputList>::DataObjectPointer
           ObjectListSource<TOutputList>
@@ -48,7 +51,9 @@ namespace otb
     return static_cast<itk::DataObject*>(TOutputList::New().GetPointer());
   }
 
-
+  /**
+   *
+   */
   template <class TOutputList>
       typename ObjectListSource<TOutputList>::OutputListType *
           ObjectListSource<TOutputList>
@@ -60,9 +65,24 @@ namespace otb
     }
   
     return static_cast<TOutputList*>
-        (this->ProcessObject::GetOutput(0));
+        (this->Superclass::GetOutput(0));
   }
   
+  /**
+   *
+   */
+  template <class TOutputList>
+      typename ObjectListSource<TOutputList>::OutputListType *
+      ObjectListSource<TOutputList>
+  ::GetOutput(unsigned int idx)
+  {
+    return static_cast<TOutputList*>
+        (this->Superclass::GetOutput(idx));
+  }
+  
+  /**
+   *
+   */ 
   template<class TOutputList>
       void
       ObjectListSource<TOutputList>
@@ -71,7 +91,9 @@ namespace otb
     this->GraftNthOutput(0, graft);
   }
      
-         
+  /**
+   *
+   */
   template<class TOutputList>
       void
       ObjectListSource<TOutputList>