Skip to content

Commit

Permalink
Improve javadoc for some addons (openhab#15701)
Browse files Browse the repository at this point in the history
Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>
  • Loading branch information
holgerfriedrich authored Oct 7, 2023
1 parent f8bcfb0 commit f24a430
Show file tree
Hide file tree
Showing 275 changed files with 547 additions and 406 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
import org.slf4j.LoggerFactory;

/**
* Monitors <openHAB-conf>/automation/ruby for Ruby files, but not libraries in lib or gems
* Monitors {@code <openHAB-conf>/automation/ruby} for Ruby files, but not libraries in lib or gems
*
* @author Cody Cutrer - Initial contribution
* @author Jan N. Klug - Refactored to new WatchService
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@
* @author Dan Cunningham - Script injections
* @author Florian Hotze - Create lock object for multi-thread synchronization; Inject the {@link JSRuntimeFeatures}
* into the JS context; Fix memory leak caused by HostObject by making HostAccess reference static; Switch to
* {@link Lock} for multi-thread synchronization; globals & openhab-js injection code caching
* {@link Lock} for multi-thread synchronization; globals and openhab-js injection code caching
*/
public class OpenhabGraalJSScriptEngine
extends InvocationInterceptingScriptEngineWithInvocableAndAutoCloseable<GraalJSScriptEngine> {
Expand Down Expand Up @@ -142,8 +142,8 @@ public class OpenhabGraalJSScriptEngine
private final boolean injectionCachingEnabled;

/**
* Creates an implementation of ScriptEngine (& Invocable), wrapping the contained engine, that tracks the script
* lifecycle and provides hooks for scripts to do so too.
* Creates an implementation of ScriptEngine {@code (& Invocable)}, wrapping the contained engine,
* that tracks the script lifecycle and provides hooks for scripts to do so too.
*/
public OpenhabGraalJSScriptEngine(boolean injectionEnabled, boolean injectionCachingEnabled,
JSScriptServiceUtil jsScriptServiceUtil, JSDependencyTracker jsDependencyTracker) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
import org.osgi.service.component.annotations.Reference;

/**
* Monitors <openHAB-conf>/automation/js for Javascript files, but not libraries
* Monitors {@code <openHAB-conf>/automation/js} for Javascript files, but not libraries
*
* @author Jonathan Gilbert - Initial contribution
* @author Jan N. Klug - Refactored to new WatchService
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ public interface AhaCollectionSchedule {

/**
* Returns the next collection dates per {@link WasteType}.
*
* @throws IOException
*/
Map<WasteType, CollectionDate> getCollectionDates() throws IOException;
}
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@
import jcifs.smb.SmbFile;

/**
* Autodiscovery for AirVisual Node by searching for a host advertised with the NetBIOS name 'AVISUAL-<SerialNumber>'.
* Autodiscovery for AirVisual Node by searching for a host advertised with the NetBIOS name
* {@code 'AVISUAL-<SerialNumber>'}.
*
* @author Victor Antonovich - Initial contribution
*/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
import org.slf4j.LoggerFactory;

/**
* The {@link ZoneHandler} is responsible for handling wired zones (i.e. REL & EXP messages).
* The {@link ZoneHandler} is responsible for handling wired zones (i.e. REL &amp; EXP messages).
*
* @author Bob Adair - Initial contribution
* @author Bill Forsyth - Initial contribution
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,8 @@ public static ADCommand reboot() {

/**
* Construct an AD configuration command. If configParam is null, a query configuration command will be created.
* If configParam consists of one or more NAME=value pairs (separated by '&' characters), a set configuration
* command will be created. The validity of configParam is not checked.
* If configParam consists of one or more NAME=value pairs (separated by {@code '&'} characters), a set
* configuration command will be created. The validity of configParam is not checked.
*
* @param configParam String containing parameters to set or null
* @return ADCommand object containing the constructed command
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@
*
* @author Gerhard Riegler - Initial contribution
* @author Christoph Weitkamp - Introduced UoM
* @see based on the calculations of
* http://www.computus.de/mondphase/mondphase.htm azimuth/elevation and
* zodiac based on http://lexikon.astronomie.info/java/sunmoon/
* @implNote based on the calculations of
* http://www.computus.de/mondphase/mondphase.htm azimuth/elevation and
* zodiac based on http://lexikon.astronomie.info/java/sunmoon/
*/
public class MoonCalc {
private static final double NEW_MOON = 0;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
* Calculates the seasons of the year.
*
* @author Gerhard Riegler - Initial contribution
* @see based on the calculations of http://stellafane.org/misc/equinox.html
* @implNote based on the calculations of http://stellafane.org/misc/equinox.html
*/
public class SeasonCalc {
private int currentYear;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
*
* @author Gerhard Riegler - Initial contribution
* @author Christoph Weitkamp - Introduced UoM
* @see based on the calculations of http://www.suncalc.net
* @implNote based on the calculations of http://www.suncalc.net
*/
public class SunCalc {
private static final double J2000 = 2451545.0;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ protected void startDiscoveryScheduler() {
/**
* Stops a scheduler.
*
* @param scheduler ScheduledFeature<?> which should be stopped
* @param scheduler {@code ScheduledFeature<?>} which should be stopped
*/
protected void stopScheduler(@Nullable ScheduledFuture<?> scheduler) {
if (scheduler != null) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ private void messageReceive(String message) {
* {@inheritDoc}
*
* Stops the discovery scan. We set {@link #scanning} to false (allowing the listening threads to end naturally
* within {@link #TIMEOUT) * 5 time then shutdown the {@link #executorService}
* within {@link #TIMEOUT} * 5 time then shutdown the {@link ExecutorService}
*/
@Override
protected synchronized void stopScan() {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,13 +62,13 @@
* binding allows openHAB to both monitor and control a pool system through
* these controllers.
*
* @see <a href="http://Autelis.com">http://autelis.com</a>
* @see <a href="http://www.autelis.com/wiki/index.php?title=Pool_Control_HTTP_Command_Reference"</a> for Jandy API
* @see <a href="http://www.autelis.com/wiki/index.php?title=Pool_Control_(PI)_HTTP_Command_Reference"</a> for Pentair
* API
* The {@link AutelisHandler} is responsible for handling commands, which
* are sent to one of the channels.
*
* The {@link AutelisHandler} is responsible for handling commands, which
* are sent to one of the channels.
* @see <a href="http://Autelis.com">http://autelis.com</a>
* @see <a href="http://www.autelis.com/wiki/index.php?title=Pool_Control_HTTP_Command_Reference">for Jandy API</a>
* @see <a href="http://www.autelis.com/wiki/index.php?title=Pool_Control_(PI)_HTTP_Command_Reference">for Pentair
* API</a>
*
* @author Dan Cunningham - Initial contribution
* @author Svilen Valkanov - Replaced Apache HttpClient with Jetty
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
* devicelist version 1 (currently used by AVM) response:
*
* <pre>
* {@code
* <devicelist version="1">
* <device identifier="##############" id="##" functionbitmask="2944" fwversion="03.83" manufacturer="AVM" productname=
* "FRITZ!DECT 200">
Expand Down Expand Up @@ -73,8 +74,8 @@
* </hkr>
* </device>
* </devicelist>
*
* <pre>
* }
* </pre>
*
* @author Robert Bausdorf - Initial contribution
* @author Christoph Weitkamp - Added support for groups
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -222,8 +222,8 @@ public String toString() {

/**
* Converts a celsius value to a FRITZ!Box value.
* Valid celsius values: 8 to 28 °C > 16 to 56
* 16 <= 8°C, 17 = 8.5°C...... 56 >= 28°C, 254 = ON, 253 = OFF
* Valid celsius values: 8 to 28 °C > 16 to 56,
* 16 &lt;= 8°C, 17 = 8.5°C...... 56 >= 28°C, 254 = ON, 253 = OFF
*
* @param celsiusValue The celsius value to be converted
* @return The FRITZ!Box value
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,7 @@ public String getURL(String path) {
* Constructs an URL from the stored information, a specified path and a specified argument string
*
* @param path Path to include in URL
* @param args String of arguments, in standard HTTP format (arg1=value1&arg2=value2&...)
* @param args String of arguments, in standard HTTP format ({@code arg1=value1&arg2=value2&...})
* @return URL
*/
public String getURL(String path, String args) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ public HeritableFuture(Future<?> parent) {
*
* {@inheritDoc}
*
* @implSpec
* @implNote
* This implementation returns a new HeritableFuture instance that uses
* the current instance as a parent. Cancellation of the child will result in
* cancellation of the parent.
Expand Down Expand Up @@ -85,7 +85,7 @@ protected void setParentFuture(Supplier<@Nullable Future<?>> futureSupplier) {
*
* {@inheritDoc}
*
* @implSpec
* @implNote
* This implementation cancels this future first, then cancels the parent future.
*/
@Override
Expand All @@ -107,7 +107,7 @@ public boolean cancel(boolean mayInterruptIfRunning) {
*
* {@inheritDoc}
*
* @implSpec
* @implNote
* This implementation will treat the future returned by the function as a parent future.
*/
@Override
Expand All @@ -120,7 +120,7 @@ public <U> CompletableFuture<U> thenCompose(Function<? super T, ? extends Comple
*
* {@inheritDoc}
*
* @implSpec
* @implNote
* This implementation will treat the future returned by the function as a parent future.
*/
@Override
Expand All @@ -133,7 +133,7 @@ public <U> CompletableFuture<U> thenComposeAsync(Function<? super T, ? extends C
*
* {@inheritDoc}
*
* @implSpec
* @implNote
* This implementation will treat the future returned by the function as a parent future.
*/
@Override
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,6 @@ public class BPUPListener implements Runnable {
* Constructor of the receiver runnable thread.
*
* @param bridgeHandler The handler of the Bond Bridge
* @throws SocketException is some problem occurs opening the socket.
*/
public BPUPListener(BondBridgeHandler bridgeHandler) {
logger.debug("Starting BPUP Listener...");
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -261,8 +261,8 @@ protected void postRequest(String path) throws IndegoAuthenticationException, In
/**
* Sends a PUT/POST request to the server.
*
* @param method the type of request ({@link org.eclipse.jetty.http.HttpMethod.PUT} or
* {@link org.eclipse.jetty.http.HttpMethod.POST})
* @param method the type of request ({@link org.eclipse.jetty.http.HttpMethod#PUT} or
* {@link org.eclipse.jetty.http.HttpMethod#POST})
* @param path the relative path to which the request should be sent
* @param requestDto the DTO which should be sent to the server as JSON
* @throws IndegoAuthenticationException if request was rejected as unauthorized
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ public void setPredictiveExclusionTime(final DeviceCalendarResponse calendar)
}

/**
* Request map position updates for the next ({@link count} * {@link interval}) number of seconds.
* Request map position updates for the next ({@code count} * {@code interval}) number of seconds.
*
* @param count number of updates
* @param interval number of seconds between updates
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ public class IndegoTypeDatabase {
/**
* Return tool name from tool type number.
*
* @see https://www.boschtoolservice.com/gb/en/boschdiy/spareparts/search-results?q=Indego
* @see <a href=
* "https://www.boschtoolservice.com/gb/en/boschdiy/spareparts/search-results?q=Indego">
* https://www.boschtoolservice.com/gb/en/boschdiy/spareparts/search-results?q=Indego</a>
*
* @param toolTypeNumber condensed tool type number, e.g. "3600HA2200" rather than "3 600 HA2 200".
* @return tool type name
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,7 @@ protected BoschSHCHandler(Thing thing) {
public abstract @Nullable String getBoschID();

/**
* Initializes this handler. Use this method to register all services of the device with
* {@link #registerService(TService, Consumer<TState>, Collection<String>, boolean)}.
* Initializes this handler.
*/
@Override
public void initialize() {
Expand Down Expand Up @@ -165,7 +164,8 @@ public void processUpdate(String serviceName, @Nullable JsonElement stateData) {
}

/**
* Should be used by handlers to create their required services.
* Use this method to register all services of the device with
* {@link #registerService(BoschSHCService, Consumer, Collection, boolean)}.
*/
protected void initializeServices() throws BoschSHCException {
}
Expand Down Expand Up @@ -193,7 +193,7 @@ protected BridgeHandler getBridgeHandler() throws BoschSHCException {
/**
* Query the Bosch Smart Home Controller for the state of the service with the specified name.
*
* @note Use services instead of directly requesting a state.
* @implNote Use services instead of directly requesting a state.
*
* @param stateName Name of the service to query
* @param classOfT Class to convert the resulting JSON to
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
import com.google.gson.JsonSyntaxException;

/**
* HTTP client using own context with private & Bosch Certs
* HTTP client using own context with private and Bosch Certs
* to pair and connect to the Bosch Smart Home Controller.
*
* @author Gerd Zanker - Initial contribution
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
import org.openhab.core.thing.ThingTypeUID;

/**
* The {@link BoseSoundTouchBindinConstants} class defines common constants, which are
* The {@link BoseSoundTouchBindingConstants} class defines common constants, which are
* used across the whole binding.
*
* @author Christian Niessner - Initial contribution
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ public CommandExecutor(BoseSoundTouchHandler handler) {
* Synchronizes the underlying storage container with the current value for the presets stored on the player
* by updating the available ones and deleting the cleared ones
*
* @param playerPresets a Map<Integer, ContentItems> containing the items currently stored on the player
* @param playerPresets a {@code Map<Integer, ContentItems>} containing the items currently stored on the player
*/
public void updatePresetContainerFromPlayer(Map<Integer, ContentItem> playerPresets) {
playerPresets.forEach((k, v) -> {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ public interface SmartherAccountHandler extends ThingHandler {
*
* @return the list of registered plants, or an empty {@link List} in case of no plants found
*
* @throws {@link SmartherGatewayException}
* @throws SmartherGatewayException
* in case of communication issues with the Smarther API
*/
List<Plant> getPlants() throws SmartherGatewayException;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ public ModuleSettings(String plantId, String moduleId) {
* @param chronothermostat
* the chronothermostat dto to get data from
*
* @throws {@link SmartherIllegalPropertyValueException}
* @throws SmartherIllegalPropertyValueException
* if at least one of the module properties cannot be mapped to any valid enum value
*/
public void updateFromChronothermostat(Chronothermostat chronothermostat)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ public static ZonedDateTime getZonedStartOfDay(int days, ZoneId zoneId) {
*
* @return a string representing the local date and time object
*
* @throws DateTimeException if an error occurs during printing
* @throws DateTimeParseException if an error occurs during printing
*/
public static String format(LocalDateTime date, String pattern) {
DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);
Expand All @@ -133,7 +133,7 @@ public static String format(LocalDateTime date, String pattern) {
*
* @return a string representing the date and time with timezone object
*
* @throws DateTimeException if an error occurs during printing
* @throws DateTimeParseException if an error occurs during printing
*/
public static String format(ZonedDateTime date, String pattern) {
DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);
Expand All @@ -153,7 +153,7 @@ public static String format(ZonedDateTime date, String pattern) {
*
* @return a string representing the range between the two local date and time objects
*
* @throws DateTimeException if an error occurs during printing
* @throws DateTimeParseException if an error occurs during printing
*/
public static String formatRange(LocalDateTime date1, LocalDateTime date2, String pattern) {
DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);
Expand All @@ -174,7 +174,7 @@ public static String formatRange(LocalDateTime date1, LocalDateTime date2, Strin
*
* @return a string representing the range between the two date and time with timezone objects
*
* @throws DateTimeException if an error occurs during printing
* @throws DateTimeParseException if an error occurs during printing
*/
public static String formatRange(ZonedDateTime date1, ZonedDateTime date2, String pattern) {
DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@
* The {@link DaikinBindingConstants} class defines common constants, which are
* used across the whole binding.
*
* @author Tim Waterhouse <tim@timwaterhouse.com> - Initial contribution
* @author Paul Smedley <paul@smedley.id.au> - Modifications to support Airbase Controllers
* @author Tim Waterhouse - Initial contribution
* @author Paul Smedley - Modifications to support Airbase Controllers
*/
@NonNullByDefault
public class DaikinBindingConstants {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
/**
* Exception for when an unexpected response is received from the Daikin controller.
*
* @author Tim Waterhouse <tim@timwaterhouse.com> - Initial contribution
* @author Tim Waterhouse - Initial contribution
*
*/
@NonNullByDefault
Expand Down
Loading

0 comments on commit f24a430

Please sign in to comment.