search

jzheng2017 / spotify-web-api-wrapper

Spotify API wrapper for Java
MIT License
48 stars 31 forks source link

Add JavaDoc to classes #7

Open jzheng2017 opened 3 years ago

jzheng2017 commented 3 years ago

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:

ktSuW commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

@suwindev19 Tasks

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:

Thanks very much!

jzheng2017 commented 3 years ago

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:

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

ktSuW commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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

knittmann commented 3 years ago

@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 commented 3 years ago

@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:

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

jzheng2017 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 months ago

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

rajshivu commented 1 month ago

i want to work on this task

jzheng2017 commented 4 weeks ago

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