Improve documentation shown during autocomplete in IDEs

[apokalyps1]

the documentation i can find is insufficient for the included features within this library and so all i have to go on is the short example at this page

[kevinkjt2000]

What is missing from the README that you expect to see? https://github.com/Dinnerbone/mcstatus

[kevinkjt2000]

Also, you may want to use python's builtin dir function for listing things that are associated with an object. For example, say you have a status object:

status = server.status()
print(dir(status))

[kevinkjt2000]

Closing due to lack of response. Please provide what is missing, so that we can know how to better document this project.

[apokalyps1]

sorry was impeded for a bit i think it might be a problem with the form i use python in as i use pycharm and to the best of my (very limited knowledge) when you download a library within pycharm it does not download anything other than the library sorry if this is a waste of time for you i am very new to python

http://www.avg.com/email-signature?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail Virus-free. www.avg.com http://www.avg.com/email-signature?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>

On Tue, Nov 17, 2020 at 3:34 PM Kevin Tindall notifications@github.com wrote:

Closing due to lack of response. Please provide what is missing, so that we can know how to better document this project.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/Dinnerbone/mcstatus/issues/95#issuecomment-729008667, or unsubscribe https://github.com/notifications/unsubscribe-auth/APZ2G3MOYRPRMVP7O44BBSTSQKJYJANCNFSM4TNVPMPQ .

[kevinkjt2000]

If there's something that can be done to improve documentation being shown in PyCharm, I'm open to suggestions and PRs.

[the-amaya]

Regarding the README, what attributes are available for each command?

For example, the 'status' command only lists these two attributes in the example in the README: (status.players.online, status.latency) -so what else can I get from this? I found that I am able to also get the server version, (status.version.name) but this is further complicated because the syntax is different when getting that same information from the query command (query.software.version)

[Iapetus-11]

Use the dir() function

[the-amaya]

Seems like a needlessly complex way to find something I would expect in the readme

dir of the status command: ['Players', 'Version', '__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'description', 'favicon', 'latency', 'players', 'raw', 'version']
dir of the query command: ['Players', 'Software', '__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'map', 'motd', 'players', 'raw', 'software']

not to mention that the way you call the attributes does not directly match what the dir() command reports. i.e., using the dir() command on a status object lists 'version', but if you try to call that you get a memory location. doing dir(status.version) gives this:

['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'name', 'protocol']

and that is where we can finally get status.version.name to return something useful.

[Iapetus-11]

Although I agree with you, there needs to be some more documentation, this is just basic programming. One needs to be able to look through a module's code or structure to figure out what it does / how it functions in case of no documentation. Anyways, you figured it out just fine using dir(), and learned multiple new things!

[the-amaya]

It seemed earlier in the thread there was a genuine question of what information would help people

What is missing from the README that you expect to see? https://github.com/Dinnerbone/mcstatus

Since there seems to be a finite number of attributes you can get from status, query, and ping, documenting the handful of things each can do would be nice

[apokalyps1]

im glad that this thread has been changed to more suit my original question as i didnt quite know how to state it and was new to python and self (and stackoverflow) taught and had a frankensteins monster of knowledge, another thing that would be useful is more in context examples for those like me who are new to python and coding in general i think that was part of the confusion of my original post i was so used to having such a plethora of solutions to problems as long code. especially because of my cobbled together approach to coding where this thread was the first time i learnt how to use dir i would look for solutions to simple problems in code to learn a use in context.

[kevinkjt2000]

another thing that would be useful is more in context examples for those like me who are new to python and coding in general

This is something that many documents struggle with, because existing coders make a lot of assumptions on base knowledge required. It is hard for the people writing the documentation to remember if they left any crucial pieces out. In my experience, the best documentation comes from new people voicing their feedback.

Seems like a needlessly complex way to find something I would expect in the readme

I concur that data structures should be documented somewhere. Using dir is merely a workaround for that, and it even works in cases where the data structure is unknown or dynamic. For a small project like this, putting all the details in the readme is probably okay. However, I usually prefer auto-generated docs that have a nice website with fancy clickable indexes, bright/dark theme button, etc. For example, the readme could link to a gh-pages site that is refreshed on every master build.

I opened #109 specifically for having better documentation, since this issue is already specifically about showing documentation in IDEs.

[kevinkjt2000]

Yet another better documentation issue #136 This time I feel that I can close this one in favor of the other.