Add JavaDoc to classes

[jzheng2017]

The library currently lacks a lot of JavaDoc. Almost all classes are without JavaDoc with the authorization classes as an exception.

It would be great if JavaDoc were to be added for the following classes:

• All classes in the spotify.api.interfaces package
• All private functions in the spotify.api.impl package (Overridden functions in implementation classes already inherit JavaDoc from their interface)
• All classes in the spotify.retrofit.services package
• All classes in the spotify.api.enums package
• All classes in the spotify.factories package
• All classes in the spotify.utils package
• All classes in the spotify.models package (only a brief description of the model at the top of the class)

[ktSuW]

Hi @jzheng2017 ,

I am Su, first year computer science student. I would like to work on this project. I have learnt about writing java doc for my uni OOP assignments.

I am currently learning Java Collections Frameworks and other java OOP stuff. I will go through the code , learn to understand them and will add documentations.

I will also read this as well so that I can add good javadoc. https://www.baeldung.com/javadoc
This will be my first contriubtion on GitHub if I can work on this.

Could you assign me this task?
Thanks.
Su

[CieloAngel]

I would like to work on this as well if possible. I just graduated yesterday with my BSSE and need to start becoming familiar with contributing to other projects. What is the best way to keep track of what others are working on so work is not duplicated? Do we wait to be assigned something, or do we just discuss here? I am very familiar with github when working on a group project and when working on my own items, but am not familiar with the "code of conduct" when working on open-source projects. Thank you!

[jzheng2017]

Hi @suwindev19 @CieloAngel , thank you for taking an interest in this project! I started this open source project a month ago and I did not expect to have people that want to contribute so soon. That's why I haven't set up the code of conduct, contribution guidelines, etc properly yet. This is also my first open source project so this is also new for me.

What is the best way to keep track of what others are working on so work is not duplicated? Do we wait to be assigned something, or do we just discuss here?

Good question! I don't know the best way yet, I'll have to think about that.

In the following days I will setup the guidelines properly (probably this weekend as I'm busy with school right now). So, stay tuned!

[ktSuW]

Hi @jzheng2017 and @CieloAngel ,

Thanks for your quick reply!

I need to learn how to collaborate with other team members for projects on github. So if you @CieloAngel are interested and @jzheng2017 allows us to collaborate, would you @CieloAngel be interested to collaborate with me? We both can work on this documentation project together.

I am still learning Java collections framework so I need to learn more and will try my best to collaborate with you. We could split the task between two of us. Let's we split the tasks like below. This is just an example. Let me know what package you are keen to work on and then we can decide. :)

@CieloAngel Tasks

• All classes in the spotify.api.interfaces package
• All private functions in the spotify.api.impl package (Overridden functions in implementation classes already inherit JavaDoc from their interface)

@suwindev19 Tasks

• All classes in the spotify.factories package
• All classes in the spotify.utils package
• All classes in the spotify.models package (only a brief description of the model at the top of the class)

And also I forgot to mention to you @jzheng2017. I am studying this semester so my time commimment for this project is 7 hr per week (Fridays only) until before my exams. This Friday I will spend time to:

• understand what this project does,
• read the codebase to get my head around
• brush up my git skills
• will start documentation if I have time left this Friday.
  Otherwise, I will start documenting next week. And will ask you questions if I need to clarify the things I don't understand.

Thanks very much!

[jzheng2017]

Hi @suwindev19 and @CieloAngel ,

I've been busy last week creating the contribution guidelines, they're done for now. I suggest reading that before starting.

I've also created a feature branch for writing the javadoc in called feature/javadoc. Update your forked repository so that it contains the newest commits and branches.

It's best if I take over writing Javadoc for the classes in spotify.api.interfaces, spotify.api.impl and spotify.retrofit.services (newly added to the list), as they are the core of the library. I've also added spotify.api.enums to the list.

What remains are:

• All classes in the spotify.api.enums package
• All classes in the spotify.factories package
• All classes in the spotify.utils package
• All classes in the spotify.models package (only a brief description of the model at the top of the class)

You can divide those four between the two of you. If you agree I'll assignee you two to this issue.

[ktSuW]

Hi @jzheng2017 ,

Thanks for the update and the instructions. I will go through it and will clarify with you if I am not clear. I will get the latest repo and work on it. I would like to clarify one thing. For all the changes I will make, I need to do it on feature/javadoc branch right? Due to Christmas, I might not be able to update during this period. If I cannot, I will continue to work on it after Christmas and New Year.

I have written what I did in last week in here,https://github.com/suwindev19/os_contribute_spotify-web-api-wrapper.

@CieloAngel Is that OK if I work on the spotify.models and factories tasks? Let me know what you think. If we both are happy, we can let @jzheng2017 know for the task assignment.

[jzheng2017]

@suwindev19

I would like to clarify one thing. For all the changes I will make, I need to do it on feature/javadoc branch right?

Yes, that's correct.

Due to Christmas, I might not be able to update during this period. If I cannot, I will continue to work on it after Christmas and New Year.

That's fine. The Javadoc for those packages aren't that high of a priority. But I would like them to be done 1 week after New Year at the latest (08-01-2021), because I would like to close this issue and merge the Javadoc with the main branch.

I have written what I did in last week in here,https://github.com/suwindev19/os_contribute_spotify-web-api-wrapper.

Good job documenting your learning journey, always nice to see :) (ps. the hyperlink is not working properly, I had to copy the actual text)

@CieloAngel Is that OK if I work on the spotify.models and factories tasks? Let me know what you think. If we both are happy, we can let @jzheng2017 know for the task assignment.

She hasn't responded in a while, if she still hasn't still responded by 25-12-2020, I will assume she doesn't want to participate anymore. I'll then assign you to spotify.models and spotify.factories, and depending on how fast you are you can take over her task or I can if I'm done early (or someone else of course if they want to help with this issue).

[CieloAngel]

Sorry for the late reply. I have been busy getting ready for Christmas. Actually, I want to take "cieloangel" off this task and assign it to "knittmann". That is my other github profile. I figured I should have a profile that is more "professional". I will reply here in a moment with the correct account so you can assign that one instead. I am fine taking spotify.models and spotify.factories.

[knittmann]

OK, this is the account I would like to use please.

[knittmann]

@jzheng2017 I like what you have done for
"I have written what I did in last week in here,https://github.com/suwindev19/os_contribute_spotify-web-api-wrapper."

May I ask why you did that? Did you come up with that idea on your own or did someone suggest it to you?

[jzheng2017]

@suwindev19 @knittmann , alright I've assigned you guys to the issue, please refer to the main post to see which tasks you've been assigned to. Again refer to the contributions guidelines when implementing the feature.

When writing the javadoc it should at the very least contain:

• clear description of the class, function, variable, etc
• description of the parameters (if there are any)
• description of the return value (unless it's not returning anything)
• author tag @author (the person who created the class) the format should be:
  @author <first name> <last name> (<email>) -> @author Jiankai Zheng ([email protected])
• if possible, which version the class was introduced @since java tag

Also @suwindev19 when writing javadoc for the models in spotify.models please refer to the official documentation from Spotify for the object models.
Also for each model its javadoc should also contain a link to the corresponding object model in the documentation using {@link}. For reference look at already written javadoc inside spotify.api.authorization or (some) spotify.api.interfaces.

That's all, the deadline for the javadoc is a week after New Year, which would be 08-01-2021. After that I would like to merge the changes to the main branch.

[ktSuW]

Thanks for clarifying and assigning the task @jzheng2017 . ANd also thanks for your tips for writing javadoc. I will start with factories package first and will create a pull request for review. I will try my best to work towards the deadline date.
Thanks!

[ktSuW]

Hi @jzheng2017 , I have added javadoc to the AbstractPlayableObjectDeserializer class and have created a pull request. I did it so that I get feedback from you for other classes. (Since I am still new so I have got many questions which are listed in my PR. Hope you don't mind). I will be away for 10 days and will continue with the tasks when I return. Thanks! Have a merry Christmas and a good break.

[knittmann]

@jzheng2017 Do we put you as the author of all of these classes?

[jzheng2017]

@knittmann

@jzheng2017 Do we put you as the author of all of these classes?

Yes. Currently, I have created and written all the classes in the library.

EDIT: and please put [skip ci] at the end of java doc commits to prevent build triggers

[knittmann]

Are you using something to make [skip ci] work on GitHub @jzheng2017? From what I can see, GitHub doesn't support it directly.

I also sent a PR. Please let me know if I did it correctly. I have never done a PR across forks.

[ktSuW]

Hi @jzheng2017 ,

I would like to let you know that I will not be able to meet the deadline. I am really sorry about my late reply. I am back from break yesterday and realised that I have underestimated my uni assignment workload which is due in next week. I am really sorry again. Since I am back to uni studies starting from next week, I can commit 7 hours a week on this project. Would that still be OK if I keep working on this every Friday starting from next Friday.

Again, I apolgoise for letting you know very late. Hope that I can continue to work on this project every Friday. If not, please assign me other tasks ( equivalent workload of 7 hours per week). Thanks very much for your understanding.

[jzheng2017]

Hi @suwindev19 , no worries man. School work goes first :)! I have also not finished my javadoc yet because I have also been very busy with school and stuff. So we can extend the deadline to an unknown date.

I've left feedback on your pull request in case you haven't seen it yet.

[ktSuW]

Hi @jzheng2017 ,

Thanks!! I really appreciate your understanding and extending the deadline.

I will continue to work on the javadoc every Friday.

Yes I have seen it. Thanks for giving me thorough feedback! :) I need to review git tutorials so that I can comply with the guidelines. Next Friday, I will focus on git and continue with the doc. Cheers

[ktSuW]

Hi @jzheng2017 ,

Today, I updated the AbstractPlayableObjectDeserializer class java class as per your feedback. I also spent about an hour with one software engineer and asked him questions such as how this type of API wrapper is built, and other javadoc professional practice, etc. I had issues with git so I spent about 2 hours to fix it. I need to spend more time on understanding git workflow so that I can commit and meet the guideline. The total hours I spent was only 4.5 hours due to some unexpected house tasks.

Questions

1. This is more for my learning purpose. In the programming class, I have been taught that to design anything, first I need a design plan. To get a bigger picture of this API wrapper design, I tried to look for something similar to use case diagram or class diagram, https://www.educative.io/courses/grokking-the-object-oriented-design-interview/RMlM3NgjAyR, but I couldn't find any in this repo. When this API was in the early stage, what design approach did you take so that you had a bigger picture and you know what packages you need and what classes needed to be in what package and their relationships.

2. I would like to check with you for the model classes documentation. The task you gave is to provide only a brief description of the model at the top of the class.
   For AlbumFull class, I will document as below. Could you give me feedback on this format? I would like to use your feedback to document the rest of classes in the model package.

 Class AlbumFull
@package spotify.models.albums
@author jzheng2017
@version 1.0.0
        Provides the AlbumFull with the following information
                       list of the album types
                       list of artists
                       list of available markets
                       list of copyrights
                       list of external IDs
                       list of genres
                       href link
                       id - **for this id, I could not figure out the information. What is this id? **
                       list of images
                       album 
                       popularity ranking
                       releaseDate
                       release date precision
                         tracks - for this, I check Paging class, I am not sure how I should write this?
                       type
                        uri

Plan for tomorrow
Tomorrow, I will read the followings document, learn git workflow and will try my best to create one PR for my work so far.

1. Fork and Pull Request Workflow - https://github.com/susam/gitpr
2. Linking a pull request to an issue - https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue
3. How to Write Doc Comments for the Javadoc Tool, https://www.oracle.com/ca-en/technical-resources/articles/java/javadoc-tool.html#packagecomments

Thanks!!

[ktSuW]

Hi @jzheng2017 ,

My apology. I have not been able to work on this project due to other commitment,

Thanks for all your help so far. Once I can work again, I will let you know.

[jzheng2017]

Due to inactivity the assignees have been unassigned. The issue is free to be picked up again.

[rajshivu]

i want to work on this task

[jzheng2017]

Feel free to work on it and create pull request when you're done.