{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# `inherit_docs` decorator\n",
    "\n",
    "Sometimes, it can be a challenge to make sure that the derived class and all its (inherited or overwritten) methods ihnerit the documentation strings, unless explicitly overwritten.\n",
    "\n",
    "Let us say we have a documented class `A`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "class A:\n",
    "    \"\"\"Class A doc-string.\"\"\"\n",
    "\n",
    "    def __init__(self, a):\n",
    "        self.a = a\n",
    "\n",
    "    def method1(self):\n",
    "        \"\"\"Class A method doc-string.\"\"\"\n",
    "        return self.a - 1\n",
    "\n",
    "    def method2(self):\n",
    "        \"\"\"Class A method doc-string.\"\"\"\n",
    "        return self.a + 3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, if we derive class B, by decorating it with `ubermagutil.inherit_docs` we can make sure all doc-strings are ihnerited, unless overwritten explicitly. This is also the case for methods, whose implementation is changed, but doc-string was not specified."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ubermagutil\n",
    "\n",
    "\n",
    "@ubermagutil.inherit_docs\n",
    "class B(A):\n",
    "    \"\"\"Class B doc-string.\"\"\"\n",
    "\n",
    "    def method1(self):\n",
    "        return self.a + 1\n",
    "\n",
    "    def method2(self):\n",
    "        \"\"\"New doc-string.\"\"\"\n",
    "        return self.a + 9"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From blass `B`, `method1` inherits doc-string:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Class A method doc-string.'"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "B.method1.__doc__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, doc-string of `method2` is overwritten:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'New doc-string.'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "B.method2.__doc__"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}