godot-console
godot-console copied to clipboard
quentincaffeino
Improve documentation
The documentation is a bit lacking. I'm not really away of everything this add-on can do, and I often have to dig into the source code to figure out how to do something. I'd be willing to help in this endeavor, if you can tell me how I can.
That would be really nice if you could help me with that.
What kind of information you have found that you are missing in docs?
In v3.0 of this addon I've added auto generated docs by using a custom version of gdscript-docs-maker by GDQuest. Those you can find in add-ons directory inside docs/generated. I've had to use custom version of this tool since original version does not support a lot of stuff I needed. I might try pushing it upstream but not sure if they'll accept it because it adds a lot of stuff.
It also planned to add hugo docs since docs maker supports generating them automatically.
The auto generated docs are cool, but most of the time the description and method descriptions are blank, so I didn't get a lot of use out of them.
I think having some information on the different ways to write to the console would be a good idea. I found Console.write_line, but it also looks like there's something called Console.Log.warn. I can assume that it prints a warning, but I'm not sure all the ways I can use it, or if I'm even supposed to use it. It's also not clear if their a method for printing errors, which would be useful.
The types besides TYPE_STRING and TYPE_INT are very confusing. What is TYPE_INT_ARRAY? How is the user supposed to input TYPE_VECTOR2? I looked in the auto generated docs, but again, they didn't have anything useful.
I think in general, it would be a good idea to create some documentation for all the methods that developers are supposed to be able to use, and fleshing out how the different types work would also be beneficial.
I've proposed my changes to GDQuest/gdscript-docs-maker#67, and we came to the conclusion that it won't be merged since godot 4.0 will have it's own docs generator and it would take to much effort. Until then I will merge docs maker I use into this repo.
The auto generated docs are cool, but most of the time the description and method descriptions are blank, so I didn't get a lot of use out of them.
True, it would be nice if those could have some examples. I guess this could be done through adding examples as markdown in method comments.
I found Console.write_line
There are two main methods for writing to the console which are Console.write_line and Console.write, with the only difference is that first adds new line on the end.
Console.Log is a logger utility which actually uses Console.write_line under the hood. The whole purpose of which is to give user an option what log messages to see by modifying log_level with `Console.Log.set_log_level(log_level: Console.Log.TYPE)
or if I'm even supposed to use it
You can, but it was written in the very first version just to help myself develop by logging some of the stuff and it's not ideal by any means, and I plan to update it, but it's to much work for now.
It's also not clear if their a method for printing errors
Console.Log.error(message) or Console.Log.log(message, Console.Log.ERROR)
The types besides TYPE_STRING and TYPE_INT are very confusing.
For that I wrote this doc: https://github.com/quentincaffeino/godot-console/blob/master/godot/addons/quentincaffeino-console/docs/Type.md But still it's lacking a lot.
What is TYPE_INT_ARRAY?
It is not supported yet, but you can add it yourself by extending BaseType, more info on that here, sadly also lacking good documentation with examples.
How is the user supposed to input TYPE_VECTOR2? I looked in the auto generated docs, but again, they didn't have anything useful.
True, that isn't mentioned anywhere. You just write two numbers separating them by comma: 1,2 (without a space) will give Vector(1, 2)
I think in general, it would be a good idea to create some documentation for all the methods that developers are supposed to be able to use
That is what that auto generated doc is for, because you the only stuff you shouldn't be able to use is some private stuff which isn't included in the docs. Everything else you can use. But adding some extra documentation which will be fully written by hand in tutorial style is obviously a must-have.
and fleshing out how the different types work would also be beneficial
Guess this could be also done through md docs inside comments which will be then converted into auto generated docs as I've mentioned previously.
Hope some of the information I have given will help you, if not please do not hesitate to contact me here or you can write me on discord QuentinCaffeino#9674.
Best
Have anything specific you want me to do? I wouldn't know where to start.
So I've added the custom docs generator I had into this repo, to run it you need to call make generate-docs. If you are not sure how to do that, that is totally fine, I can run this on my side after you will do some documentation on methods and properties.
I've also added docs to test that I meant with docs right in methods comments and you can see the result here: https://github.com/quentincaffeino/godot-console/blob/master/godot/addons/quentincaffeino-console/src/Console.gd#L129 https://github.com/quentincaffeino/godot-console/blob/master/godot/addons/quentincaffeino-console/docs/generated/Console.md#add_command
Not really sure, I think it really depends on what you find missing, because for me it's all ok, I know this repo from top to bottom))
Do you have any suggestions? I have only one suggestion to start small, so the first pr won't look as a full project rewrite with hundreds of changes, otherwise fill free to choose whatever you fill is required the most)
If I may suggest a few additions. A little thing first, but Godot's addons are called plugins in recent versions, so it's Projects > Plugins not Project > Addons (in the readme).
The documentation is a great start but you have to dig a bit to find it, I believe the readme should be a bit clearer and answer these questions :
- Where can I find the documentation ?
- How do I setup the console ? We know how to install but you have to search a little bit to get it working.
It's an amazing plugin by the way, I'm commenting here because I think updating the readme would make it more accessible, especially as it's already pretty easy to use.
Hey, @GuillaumeCailhe.
Thanks, I'll fix that, never actually installed add-ons through editor)
Not sure how to do it better, so if you have an idea how please feel free to open a pr, I would love to see your ideas!
Best 👍
This issue was up for quite some time without any activity so I'm closing it. If anyone would have any ideas on how to improve current docs, please open a new issue :)