import chainer
import warnings


def experimental(api_name):
    """A function for marking APIs as experimental.

    The developer of an API can mark it as *experimental* by calling
    this function. When users call experimental APIs, :class:`FutureWarning`
    is issued.
    The presentation of :class:`FutureWarning` is disabled by setting
    ``chainer.disable_experimental_warning`` to ``True``,
    which is ``False`` by default.

    The basic usage is to call it in the function or method we want to
    mark as experimental along with the API name.

    .. doctest::
        :hide:

        >>> import warnings
        ... warnings.simplefilter('always')

    .. doctest::
        >>> from chainer.utils import experimental
        ...
        ... def f(x):
        ...  experimental('chainer.foo.bar.f')
        ...  # concrete implementation of f follows
        ...
        ... f(1)
        FutureWarning: chainer.experimental.f is an experimental API. \
The interface can change in the future.

    We can also make a whole class experimental. In that case,
    we should call this function in its `__init__` method.

    >>> class C():
    ...   def __init__(self):
    ...     experimental('chainer.foo.C')
    ...
    ... C()
    FutureWarning: chainer.foo.C is an experimental API. \
The interface can change in the future

    If we want to mark ``__init__`` method only, rather than class itself.
    It is recommended that we explicitly feed its API name.

    >>> class D():
    ...   def __init__(self):
    ...     experimental('D.__init__')
    ...
    ... D()
    FutureWarning: D.__init__ is an experimental API. \
The interface can change in the future

    Currently, we do not have any sophisticated way to mark some usage of
    non-experimental function as experimental.
    But we can support such usage by explicitly branching it.

    >>> def g(x, experimental_arg=None):
    ...   if experimental_arg is not None:
    ...     experimental('experimental_arg of chainer.foo.g')

    Args:
        api_name(str): The name of an API marked as experimental.
    """

    if not chainer.disable_experimental_feature_warning:
        warnings.warn('{} is experimental. '
                      'The interface can change in the future.'.format(
                          api_name),
                      FutureWarning)

@@ -565,31 +565,18 @@
  .. 
-doc
 test
-::%0A        :hide
+setup:
 :%0A%0A 
@@ -581,20 +581,16 @@
 %0A       
- %3E%3E%3E
  import 
@@ -605,20 +605,16 @@
 %0A       
- ...
  warning
@@ -650,29 +650,27 @@
  .. 
-doc
 test
+code
 ::%0A
- 
+%0A
        
-%3E%3E%3E
  fro
@@ -705,35 +705,24 @@
 imental%0A
-        ...
 %0A       
  ... def
@@ -713,20 +713,16 @@
 %0A       
- ...
  def f(x
@@ -732,19 +732,18 @@
         
-...
+  
   experi
@@ -778,19 +778,18 @@
         
-...
+  
   # conc
@@ -821,24 +821,25 @@
 follows%0A
+%0A
         
 ...%0A    
@@ -834,28 +834,34 @@
     
-...%0A        ... f(1)
+f(1)%0A%0A    .. testoutput::%0A
 %0A   
@@ -1093,27 +1093,46 @@
 ethod.%0A%0A    
-%3E%3E%3E
+.. testcode::%0A%0A       
  class C():%0A
@@ -1127,35 +1127,37 @@
  class C():%0A    
+ 
-...
+    
    def __init__(
@@ -1163,32 +1163,34 @@
 (self):%0A    
-...
+  
      
+   
 experimental
@@ -1211,28 +1211,47 @@
 C')%0A
-    ...%0A    ... C()%0A
+%0A        C()%0A%0A    .. testoutput::%0A%0A    
     
@@ -1485,19 +1485,38 @@
 e.%0A%0A    
-%3E%3E%3E
+.. testcode::%0A%0A       
  class D
@@ -1523,19 +1523,21 @@
 ():%0A    
-...
+     
    def _
@@ -1551,27 +1551,31 @@
 (self):%0A    
-...
+       
      experim
@@ -1598,28 +1598,47 @@
 _')%0A
+%0A
     
-...%0A    ... D()%0A
+    D()%0A%0A    .. testoutput::%0A%0A    
     
@@ -1921,11 +1921,30 @@
     
-%3E%3E%3E
+.. testcode::%0A%0A       
  def
@@ -1977,19 +1977,21 @@
 e):%0A    
-...
+     
    if ex
@@ -2026,11 +2026,15 @@
     
-...
+       
     

Fix doctest