Merge #10951

10951: feat: assist to generate documentation templates r=Veykril a=numero-744

Closes #10878, #1915 and #4767

Full description is in #10878, better read [the tests](https://github.com/rust-analyzer/rust-analyzer/pull/10951/files#diff-7a64e2efb66b2625443340fcbc96d531baff12c17cc0aaf51885ea94f67de254R424) to understand what this feature does.

- [x] There is one remaining thing about non-`pub` functions, what do you think about it?
- [x] In this PR [empty examples are generated](https://github.com/rust-analyzer/rust-analyzer/pull/10951/files#diff-7a64e2efb66b2625443340fcbc96d531baff12c17cc0aaf51885ea94f67de254R99) for `trait` functions, but maybe no examples should be provided at all.
- [x] If there is already a documentation, add another one with a separator ([currently done](https://github.com/rust-analyzer/rust-analyzer/pull/10951/files#diff-7a64e2efb66b2625443340fcbc96d531baff12c17cc0aaf51885ea94f67de254R74)) or simply disable this assist?
- [x] I will check once more that the generated examples are correct (ie. they are easy to fill before that they are built and tested)

Comments appreciated 😄 

Co-authored-by: Côme ALLART <come.allart@etu.emse.fr>

crates/ide_assists/src/lib.rs

@@ -136,6 +136,7 @@ mod handlers {
     mod generate_default_from_new;
     mod generate_deref;
     mod generate_derive;
+    mod generate_documentation_template;
     mod generate_enum_is_method;
     mod generate_enum_projection_method;
     mod generate_from_impl_for_enum;
@@ -219,6 +220,7 @@ pub(crate) fn all() -> &'static [Handler] {
             generate_delegate_methods::generate_delegate_methods,
             generate_deref::generate_deref,
             generate_derive::generate_derive,
+            generate_documentation_template::generate_documentation_template,
             generate_enum_is_method::generate_enum_is_method,
             generate_enum_projection_method::generate_enum_as_method,
             generate_enum_projection_method::generate_enum_try_into_method,

crates/ide_assists/src/tests/generated.rs

@@ -839,6 +839,36 @@ struct Point {
     )
 }
 
+#[test]
+fn doctest_generate_documentation_template() {
+    check_doc_test(
+        "generate_documentation_template",
+        r#####"
+pub fn my_$0func(a: i32, b: i32) -> Result<(), std::io::Error> {
+    unimplemented!()
+}
+"#####,
+        r#####"
+/// .
+///
+/// # Examples
+///
+/// ```
+/// use test::my_func;
+///
+/// assert_eq!(my_func(a, b), );
+/// ```
+///
+/// # Errors
+///
+/// This function will return an error if .
+pub fn my_func(a: i32, b: i32) -> Result<(), std::io::Error> {
+    unimplemented!()
+}
+"#####,
+    )
+}
+
 #[test]
 fn doctest_generate_enum_as_method() {
     check_doc_test(