How to write documentation for observable return which throws exceptions in RxJava

Question

Not sure how to document throws declaration in Java doc style. Below example:

/**
 * Get Facebook Friends
 *
 * @param facebookToken - Facebook Token
 * @return list of {@link User}
 * @throws SomeCheckedException <- this is normally the way, but not for Observable return type
 */

public Observable<List<User>> getFriends(String facebookToken) {
    return get("/me/friends", facebookToken)
        .flatMap(response -> {
            FacebookResponse facebookResponse = response.readEntity(FacebookResponse.class);

            if (null != facebookResponse.getError()) {
                return Observable.error(parseException(facebookResponse.getError()));
            } else if (null == facebookResponse.getData()) {
                return Observable.error(new FacebookException("Empty data"));
            }

            return Observable.just(facebookResponse.getData());
        });
    }

The method is supposed to return Observable.error() , and I want to developer who is gonna call this method know about possibly exception do be handled in onErrorNextResume , etc.

Docs don't cover anything similar.

Answer 1

You are right, this method does not throw any errors, but it can potentially return an Observable emitting an error. In the company where I am currently working, we highly use reactive programming and for these cases, we drop the @throw line and we add this information to the @return :

@return an {@link Observable} containing the retrieved {@link User}s; yields a {@link FacebookException} in case of empty data.