[enhancement] Improvements on function documentation

[Macacoazul01]

It would be nice to have samples of complex uses of the parameters when you hover their names (some codes on the examples would be perfect).

With it, the package will become easier to use.

[Macacoazul01]

something like this (using Dialog() parameters as example):

[Macacoazul01]

@lcuis to help exemplifying what am I saying:

The default done button: {dynamic doneButton = "Done"}

What can I do with a custom done button:

doneButton: (List<int> selectedItemsDone, BuildContext doneContext) {
            return ElevatedButton(
              onPressed: () {
                Navigator.pop(doneContext);
                setState(() {});
              },
              child: const Text("Selecionar"),
          },

These complex cases are already on the example main.dart file of the project, but not on the parameters

[lcuis]

Hello @Macacoazul01 ,

I think this would definitely be a big plus to the plugin. The thing is that the only way I have found to document is by documenting the method. This method documentation is already very long. I am not sure that it would still be readable with examples for complex parameters. Do yo think otherwise?
The best for me would be for the information popup to only contain the single parameter related information but I don't know how to do that. The dart documentation doesn't mention this possibility: https://dart.dev/guides/language/effective-dart/documentation
Do you know any way to do that?

[Macacoazul01]

I'm really not the best at documentation.
If you find a way to do something like this that works i can help with, by copying the sample on other functions.
Maybe there isn't a true necessity to add a sample here, only to define a little better what every parameter is / show each one while we hover the parameter.

something like this (using Dialog() parameters as example):

[lcuis]

This is a very good example you found here. It shows it is possible to have hover documentation per parameter.

Apparently, it is done by documenting the variable, which is the case in SearchChoices. The only issue is that we don't specify the single and multiple factories parameters with a preceding this.. Thus, the documentation engine cannot find the parameter documentation directly.
Maybe, we should transform the 2 factories into simple constructors and have them defined with all the parameters set as preceded with this.?

For this, we probably need to remove the existing constructor _ and place all its assert calls within a method called by both new constructors.

Also, indeed, it is possible and a good idea to improve the content of the existing documentation.

[lcuis]

Release 2.2.4 is a good starting point to improve the parameters documentation. Now, it is possible to have a hover documentation per parameter and thus have an example for the most complex cases.

Also, with this release, removing the _ constructor meant a quite important simplification.

Thanks @Macacoazul01 !

[Macacoazul01]

closing this one