pyln-client: Deprecate category, description and long description fro…

…m method

Category, description and long description from `json_command` and `plugin_command` have been removed in favour of getting them from json schema.  Reference PR: Add categories in RPC documentation ElementsProject#7485

Deprecating them in pyln-client as well. They will remove completely in future releases.

Changelog-None.

contrib/pyln-client/pyln/client/plugin.py

@@ -48,15 +48,11 @@ class Method(object):
     """
     def __init__(self, name: str, func: Callable[..., JSONType],
                  mtype: MethodType = MethodType.RPCMETHOD,
-                 category: str = None, desc: str = None,
-                 long_desc: str = None, deprecated: Union[bool, List[str]] = None):
+                 deprecated: Union[bool, List[str]] = None):
         self.name = name
         self.func = func
         self.mtype = mtype
-        self.category = category
         self.background = False
-        self.desc = desc
-        self.long_desc = long_desc
         self.deprecated = deprecated
         self.before: List[str] = []
         self.after: List[str] = []
@@ -327,9 +323,6 @@ def convert_featurebits(
 
     def add_method(self, name: str, func: Callable[..., Any],
                    background: bool = False,
-                   category: Optional[str] = None,
-                   desc: Optional[str] = None,
-                   long_desc: Optional[str] = None,
                    deprecated: Optional[Union[bool, List[str]]] = None) -> None:
         """Add a plugin method to the dispatch table.
 
@@ -357,9 +350,6 @@ def add_method(self, name: str, func: Callable[..., Any],
         `request.set_result` or `result.set_exception` to return a result or
         raise an exception for the call.
 
-        The `category` argument can be used to specify the category of the
-        newly created rpc command.
-
         `deprecated` True means that it won't appear unless `allow-deprecated-apis`
         is true (the default), or if list of version string (e.g. "v23.08"), then
         start deprecation cycle at that version (and removal after second entry in list).
@@ -370,11 +360,7 @@ def add_method(self, name: str, func: Callable[..., Any],
             )
 
         # Register the function with the name
-        method = Method(
-            name, func, MethodType.RPCMETHOD, category, desc, long_desc,
-            deprecated
-        )
-
+        method = Method(name, func, MethodType.RPCMETHOD, deprecated)
         method.background = background
         self.methods[name] = method
 
@@ -497,9 +483,10 @@ def async_method(self, method_name: str, category: Optional[str] = None,
         Internally uses add_method.
         """
         def decorator(f: Callable[..., None]) -> Callable[..., None]:
-            self.add_method(method_name, f, background=True, category=category,
-                            desc=desc, long_desc=long_desc,
-                            deprecated=deprecated)
+            for attr, attr_name in [(category, "Category"), (desc, "Description"), (long_desc, "Long description")]:
+                if attr is not None:
+                    self.log("{} is deprecated but defined in method {}; it will be ignored by Core Lightning".format(attr_name, method_name), level="warn")
+            self.add_method(method_name, f, background=True, deprecated=deprecated)
             return f
         return decorator
 
@@ -512,13 +499,10 @@ def method(self, method_name: str, category: Optional[str] = None,
         Internally uses add_method.
         """
         def decorator(f: Callable[..., JSONType]) -> Callable[..., JSONType]:
-            self.add_method(method_name,
-                            f,
-                            background=False,
-                            category=category,
-                            desc=desc,
-                            long_desc=long_desc,
-                            deprecated=deprecated)
+            for attr, attr_name in [(category, "Category"), (desc, "Description"), (long_desc, "Long description")]:
+                if attr is not None:
+                    self.log("{} is deprecated but defined in method {}; it will be ignored by Core Lightning".format(attr_name, method_name), level="warn")
+            self.add_method(method_name, f, background=False, deprecated=deprecated)
             return f
         return decorator
 
@@ -957,13 +941,8 @@ def _getmanifest(self, **kwargs) -> JSONType:
 
             methods.append({
                 'name': method.name,
-                'category': method.category if method.category else "plugin",
-                'usage': " ".join(args),
-                'description': doc if not method.desc else method.desc
+                'usage': " ".join(args)
             })
-            if method.long_desc:
-                m = methods[len(methods) - 1]
-                m["long_description"] = method.long_desc
 
         manifest = {
             'options': list(d.json() for d in self.options.values()),

doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md

@@ -51,14 +51,11 @@ The `getmanifest` method is required for all plugins and will be called on start
   "rpcmethods": [
     {
       "name": "hello",
-      "usage": "[name]",
-      "description": "Returns a personalized greeting for {greeting} (set via options)."
+      "usage": "[name]"
     },
     {
       "name": "gettime",
       "usage": "",
-      "description": "Returns the current time in {timezone}",
-      "long_description": "Returns the current time in the timezone that is given as the only parameter.\nThis description may be quite long and is allowed to span multiple lines.",
       "deprecated": false
     }
   ],
@@ -101,7 +98,7 @@ The `getmanifest` method is required for all plugins and will be called on start
 
 During startup the `options` will be added to the list of command line options that `lightningd` accepts. If any `options` "name" is already taken startup will abort. The above will add a `--greeting` option with a default value of `World` and the specified description. _Notice that currently string, integers, bool, and flag options are supported._ If an option specifies `dynamic`: `true`, then it should allow a `setconfig` call for that option after initialization.
 
-The `rpcmethods` are methods that will be exposed via `lightningd`'s JSON-RPC over Unix-Socket interface, just like the builtin commands. Any parameters given to the JSON-RPC calls will be passed through verbatim. Notice that the `name`, `description` and `usage` fields are mandatory, while the `long_description` can be omitted (it'll be set to `description` if it was not provided). `usage` should surround optional parameter names in `[]`.
+The `rpcmethods` are methods that will be exposed via `lightningd`'s JSON-RPC over Unix-Socket interface, just like the builtin commands. Any parameters given to the JSON-RPC calls will be passed through verbatim. Notice that the `name` and `usage` fields are mandatory. `usage` should surround optional parameter names in `[]`.
 
 `options` and `rpcmethods` can mark themselves `deprecated: true` if you plan on removing them: this will disable them if the user sets `allow-deprecated-apis` to false, or in `--developer` mode.  You can also specify `deprecated` as an array of one or two version numbers, indicating when deprecation starts, and the final version it will be permitted, e.g. `"deprecated": ["v24.02", "v24.02"]`.  If only one version number is given, then the final version will be 6 months after the start version.
 

doc/developers-guide/plugin-development/json-rpc-passthrough.md

@@ -7,9 +7,7 @@ updatedAt: "2023-02-03T08:53:50.840Z"
 ---
 Plugins may register their own JSON-RPC methods that are exposed through the JSON-RPC provided by `lightningd`. This provides users with a single interface to interact with, while allowing the addition of custom methods without having to modify the daemon itself.
 
-JSON-RPC methods are registered as part of the `getmanifest` result. Each registered method must provide a `name` and a `description`. An optional `long_description` may also be  
-provided. This information is then added to the internal dispatch table, and used to return the help text when using `lightning-cli
-help`, and the methods can be called using the `name`.
+JSON-RPC methods are registered as part of the `getmanifest` result. Each registered method must provide a `name`. This information is then added to the internal dispatch table, and used to return the help text when using `lightning-cli help`, and the methods can be called using the `name`.
 
 For example, `getmanifest` result will register two methods, called `hello` and `gettime`:
 
@@ -18,14 +16,11 @@ For example, `getmanifest` result will register two methods, called `hello` and
   "rpcmethods": [
     {
       "name": "hello",
-      "usage": "[name]",
-      "description": "Returns a personalized greeting for {greeting} (set via options)."
+      "usage": "[name]"
     },
     {
       "name": "gettime",
-      "description": "Returns the current time in {timezone}",
       "usage": "",
-      "long_description": "Returns the current time in the timezone that is given as the only parameter.\nThis description may be quite long and is allowed to span multiple lines."
     }
   ],
   ...