search

twitch4j / twitch4j.github.io

Twitch4J Page
http://twitch4j.github.io
MIT License
4 stars 14 forks source link

Helix: Add missing documentation for endpoints #11

Open iProdigy opened 4 years ago

iProdigy commented 4 years ago

Description

These endpoints lack markdown documentation

Solutions

Add markdown docs

Additional context

Official helix documentation: https://dev.twitch.tv/docs/api/reference

Directory for markdown docs: https://github.com/twitch4j/twitch4j.github.io/tree/master/docs/versioned_docs/version-1.x/rest-helix

Method definitions: https://github.com/twitch4j/twitch4j/blob/master/rest-helix/src/main/java/com/github/twitch4j/helix/TwitchHelix.java

Javadoc: https://twitch4j.github.io/javadoc/com/github/twitch4j/helix/TwitchHelix.html

GreatGhostsss commented 3 years ago

Hi! I'd love to help out with this, if you'll have me.

PhilippHeuer commented 3 years ago

Hi @GreatGhostsss, we would be happy about help with this.

The methods are all defined in https://github.com/twitch4j/twitch4j/blob/master/rest-helix/src/main/java/com/github/twitch4j/helix/TwitchHelix.java. Those docs for those endpoints will appear under https://twitch4j.github.io/docs/rest-helix/ once added.

We have a docs contribution page - https://twitch4j.github.io/docs/contribution/documentation/ - which is very technical about markdown currently. If you have any questions or need any information to get started feel free to ask them in here or hop into the discord chat at https://discord.gg/FQ5vgW3. We can also use that as feedback to improve our contribution page :)

There is no one else working on this right now, so you could pick one method of your choice to get started.

EleekaN commented 1 year ago

Hi, I would like to work on this task. Some of the links listed above like Directory for markdown docs: https://github.com/twitch4j/twitch4j.github.io/tree/master/content/docs/rest-helix and others are not found. Where can I get more details for the endpoints? Where should we update the docs?

iProdigy commented 1 year ago

@EleekaN thanks for your willingness to help!

Sorry about the link mixup, we had a docs overhaul & haven't updated all links. Regardless, the correct directory is: https://github.com/twitch4j/twitch4j.github.io/tree/master/docs/versioned_docs/version-1.x/rest-helix

To write these docs, it is very useful to crossreference twitch's official docs and/or twitch4j's javadocs

Also, feel free to join our Discord for more assistance

EleekaN commented 1 year ago

Thank you @iProdigy for your quick response. Let me go through the details. I will connect with you again. Will try out Discord too, for any help.

EleekaN commented 1 year ago

How can I get the code snippets? Is there a different tool I should use?

iProdigy commented 1 year ago

The method definitions can be found here: https://github.com/twitch4j/twitch4j/blob/master/rest-helix/src/main/java/com/github/twitch4j/helix/TwitchHelix.java

The example usage is new code that must be written. If you're not comfortable with writing the example snippets, I can provide some in the discord if you share which endpoint you're documenting.

EleekaN commented 1 year ago

I picked the one next in the list "GetDropsEntitlement", I haven't started documenting yet, however trying to figure out the requirements. It will be great to get some inputs from you on the example snippets. Trying to see the pattern on how snippets are documented for the other endpoints. Able to make a little sense for now, but not good enough.There are so many details and I am new with Java.

iProdigy commented 1 year ago

@EleekaN I've updated the list of methods that need documentation & improved the rough order of priority.

Feel free to continue with getDropsEntitlement as you've already started on that one. Here's the code example: https://gist.github.com/iProdigy/2e0aa5806c4ffa6d606b6445609067e7

For further code examples, just ask in the discord (& we can also assist in translating the java to kotlin or groovy)!

EleekaN commented 1 year ago

Thank you so much. I will update you soon.

EleekaN commented 1 year ago

Hi @iProdigy, greetings for the new year! Is there a way I could learn to write the code snippets? Something I can lookup or read on. I was trying to update getChannelInformation endpoint.

iProdigy commented 1 year ago

@EleekaN To write the code snippets, I'd install an IDE like IntelliJ (you can clone the twitch4j project or import the library via maven or gradle) to help out with code completion & error checking (assuming you already know Java)

Another aid is looking at existing usages... for example: https://github.com/twitch4j/twitch4j/blob/9605003e6ccbc8606ed758a58d6f110d5d1a2807/rest-helix/src/test/java/com/github/twitch4j/helix/endpoints/ChannelServiceTest.java#L33 (also sometimes we have snippets already posted in the discord - try a search)