updated copyright message

[modules/kernel.git] / src / KERNEL_PY / kernel / deprecation.py

diff --git a/src/KERNEL_PY/kernel/deprecation.py b/src/KERNEL_PY/kernel/deprecation.py
index 5b9d4871e6c987680cd683e6c478513e3794f617..30db961f2cdad41dc6b8f0acdf75ccfbd472eeed 100644 (file)
--- a/src/KERNEL_PY/kernel/deprecation.py
+++ b/src/KERNEL_PY/kernel/deprecation.py
@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2007-2012  CEA/DEN, EDF R&D, OPEN CASCADE
+# Copyright (C) 2007-2023  CEA, EDF, OPEN CASCADE
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
 # License as published by the Free Software Foundation; either
-# version 2.1 of the License.
+# version 2.1 of the License, or (at your option) any later version.
 #
 # This library is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -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))