X-Git-Url: http://git.salome-platform.org/gitweb/?a=blobdiff_plain;f=src%2FKERNEL_PY%2Fkernel%2Fdeprecation.py;h=81c82d495226849e4de46734f398016468c97c65;hb=dac5e4d5c8f771e0cedb7caa5292bc54be5ca89a;hp=46d431b1200cf7438e93fa93ba3191416f3347a0;hpb=63414a08d9492c25c206579c1953ec6f390679fd;p=modules%2Fkernel.git

diff --git a/src/KERNEL_PY/kernel/deprecation.py b/src/KERNEL_PY/kernel/deprecation.py
index 46d431b12..81c82d495 100644
--- a/src/KERNEL_PY/kernel/deprecation.py
+++ b/src/KERNEL_PY/kernel/deprecation.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007-2014  CEA/DEN, EDF R&D, OPEN CASCADE
+# Copyright (C) 2007-2016  CEA/DEN, EDF R&D, OPEN CASCADE
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -18,6 +18,21 @@
 #
 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
 #
+
+## \defgroup deprecation deprecation
+#  \{ 
+#  \details
+#  This module provides several functions to indicate the deprecation of a
+#  module, a method or a function.
+#  \code
+#  from salome.kernel.deprecation import deprecated
+#  deprecated("Deprecated since version 6.3.0. Consider replacement with 
+#              newFunction()")
+#  def oldFunction():
+#  ...
+#  \endcode
+#  \}
+
 """
 This module provides several functions to indicate the deprecation of a
 module, a method or a function.
@@ -63,6 +78,13 @@ def __deprecated_with_msg(func, msg):
         return func(*args, **kwargs)
     return new_func
 
+## This is a decorator which can be used to mark functions
+#  as deprecated. It will result in a warning being emitted
+#  when the function is used. The message in parameter will
+#  be displayed and should indicate how this function can be
+#  replaced. If the terminal can display colors, the warning
+#  messages will appear in blue.
+#  \ingroup deprecation
 def deprecated(msg = msg_seedoc):
     """
     This is a decorator which can be used to mark functions
@@ -83,6 +105,13 @@ def deprecated(msg = msg_seedoc):
             return g
     return make_dep
 
+## This function can be used to mark a module as deprecated.
+#  It must be called explicitly at the beginning of the deprecated
+#  module. It will result in a warning being emitted. The message
+#  in parameter will be displayed and should indicate how this
+#  module can be replaced. If the terminal can display colors,
+#  the warning messages will appear in blue.
+#  \ingroup deprecation
 def deprecated_module(msg = msg_seedoc):
     """
     This function can be used to mark a module as deprecated.
@@ -102,6 +131,11 @@ def deprecated_module(msg = msg_seedoc):
             stacklevel = 5
         )
 
+## Determine if the calling code is ultimately called by sphinx to generate
+#  documentation. The result can be used to conditionally inhibit the
+#  decorators or some Salome-related imports that fail when called outside
+#  Salome.
+#  \ingroup deprecation
 def is_called_by_sphinx():
     """
     Determine if the calling code is ultimately called by sphinx to generate
@@ -115,7 +149,9 @@ def is_called_by_sphinx():
 
 
 def __show_colored_warning(message, category, filename,
-                           lineno, file = sys.stderr, line = None):
+                           lineno, file = None, line = None):
+    if file is None:
+        file = sys.stderr
     str = warnings.formatwarning(message, category, filename, lineno, line)
     if category == DeprecationWarning and termcolor.canDisplayColor(file):
         file.write(termcolor.makeColoredMessage(str, termcolor.BLUE))