search

dariuszseweryn / RxAndroidBle

An Android Bluetooth Low Energy (BLE) Library with RxJava3 interface
http://polidea.github.io/RxAndroidBle/
Apache License 2.0
3.43k stars 583 forks source link

Update JavaDocs #169

Open IgorGanapolsky opened 7 years ago

IgorGanapolsky commented 7 years ago

Summary

Hello, thank you for creating this advanced library for BLE scanning based on RxJava. I am trying to look through your code to get inspiration on how to use it in my own project, and to understand it better. I am wondering - can you add more JavaDocs throughout your code? At least on the public methods. As it stands, the code is very sophisticated and not trivial to follow. Furthermore, RxJava has a high learning curve, which adds necessity to have better documentation throughout the codebase.

Preconditions

Look through the existing code.

Expected result

There need to be JavaDocs on public members.

dariuszseweryn commented 7 years ago

Hello @IgorGanapolsky Thanks for the insight. I will add your request to my TODOs. Besides: which public methods do not have JacaDoc? I am trying to keep at least the API as documented as possible.

IgorGanapolsky commented 7 years ago

Thank you. I am looking at OperationPriorityFifoBlockingQueue, RxBleClientImpl, and RxBleRadioImpl.

dariuszseweryn commented 7 years ago

The interface of OperationPriorityFifoBlockingQueue is just a wrapper for a PriorityBlockingQueue intended to use with operations — it is a quite simple class. RxBleRadioImpl is basically a worker which is responsible for serializing operations and RxBleClientImpl is the implementation of the entry point to the library. Anything in particular is hard to comprehend? On which things should I concentrate describing?

IgorGanapolsky commented 7 years ago

@dariuszseweryn Essentially putting what you just said in a JavaDoc comment for class declarations would be great. The code may seem intuitive and straightforward to smart engineers like you :) , but believe me - this code is very non-trivial for newbies to BLE and those who are not experts in RxJava. Additionally, each public method having a JavaDoc comment would make it a lot clearer to follow.

dariuszseweryn commented 7 years ago

Skip the flattery. ;) I know that diving into code that was written by others is not easy. I will try to add more comments and JavaDoc when I will have a moment.

RobLewis commented 7 years ago

I sympathize. The project I'm on has involved simultaneously learning Android, RxJava, and BLE. I think "drinking from a firehose" is an apt way to put it :-) Additional documentation is always a welcome thing.

kenwdelong commented 7 years ago

Sorry, but also, are the javadocs hosted anywhere?

dariuszseweryn commented 7 years ago

@kenwdelong they are available in the .aar you get from the Maven repository.