Skip to content

Commit

Permalink
ElektraInitiative#3713 nerfed javadoc checking and ran formatter
Browse files Browse the repository at this point in the history
  • Loading branch information
Michael Tucek authored and a-kraschitzer committed Apr 14, 2021
1 parent fc8a5f2 commit 9de0cb1
Show file tree
Hide file tree
Showing 6 changed files with 419 additions and 328 deletions.
4 changes: 2 additions & 2 deletions doc/news/_preparation_next_release.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,9 +184,9 @@ you up to date with the multi-language support provided by Elektra.
Until internal `KeySet` iterator support has been dropped form native library, `Elektra::ksRewind` is being retained while also being annotated as 'deprecated for removal'. The reason is, that we still need to rewind a `KeySet` before passing it to a native plugin via `NativePlugin::set`, `NativePlugin::get` or `NativePlugin::error`. _(@tucek)_
Furthermore `Elektra::ksPop` and `KeySet::pop` have been removed and `KeySet::remove` has been introduced as replacment.
Until internal `KeySet` iterator support has been dropped form native library, `Elektra::ksRewind` is being retained while also being annotated as 'depricated for removal'. The reason is, that we still need to rewind a `KeySet` before passing it to a native plugin via `NativePlugin::set`, `NativePlugin::get` or `NativePlugin::error`. _(@tucek)_
Until internal `KeySet` iterator support has been dropped form native library, `Elektra::ksRewind` is being retained while also being annotated as 'depricated for removal'. The reason is, that we still need to rewind a `KeySet` before passing it to a native plugin via `NativePlugin::set`, `NativePlugin::get` or `NativePlugin::error`. _(@tucek)_
Further more `Elektra::ksPop` and `KeySet::pop` have been removed and `KeySet::remove` has been introduced as replacment. _(Michael Tucek)_
Further more `Elektra::ksPop` and `KeySet::pop` have been removed and `KeySet::remove` has been introduced as replacment. _(Michael Tucek)_
- Migrated to Gradle project _(Michael Tucek)_
Expand Down
5 changes: 4 additions & 1 deletion src/bindings/jna/java-shared.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,10 @@ tasks.named('javadoc').configure {
}

// TODO #3754 reactivate: fail on warnings and warn about non-compliant javadoc syntax
//options.addStringOption('Xwerror', '-Xdoclint:all')
//options.addStringOption('Xwerror', '-quiet')
//options.addStringOption('Xdoclint:all', '-quiet')
options.addStringOption('Xdoclint:-missing', '-quiet')
options.addStringOption('Xdoclint:all', '-quiet')
}

javadoc {
Expand Down
178 changes: 91 additions & 87 deletions src/bindings/jna/libelektra/src/main/java/org/libelektra/Elektra.java
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ public interface Elektra extends Library {
/**
* Singleton instance of the native library proxy.
*/
Elektra INSTANCE = Native.loadLibrary("elektra-kdb", Elektra.class);
Elektra INSTANCE = Native.loadLibrary ("elektra-kdb", Elektra.class);

// KDB methods --------------------------------------------------------------

Expand Down Expand Up @@ -47,8 +47,7 @@ public interface Elektra extends Library {
* <li>{@code null} on failure</li>
* </ul>
*/
@Nullable
Pointer kdbOpen(@Nullable Pointer contractKeySet, Pointer errorKey);
@Nullable Pointer kdbOpen (@Nullable Pointer contractKeySet, Pointer errorKey);

/**
* Closes the session with the Key database.<br >
Expand All @@ -71,7 +70,7 @@ public interface Elektra extends Library {
* <li>{@code -1} on {@code null} pointer passed</li>
* </ul>
*/
int kdbClose(Pointer handle, Pointer errorKey);
int kdbClose (Pointer handle, Pointer errorKey);

/**
* Retrieve keys in an atomic and universal way.<br >
Expand Down Expand Up @@ -136,7 +135,7 @@ public interface Elektra extends Library {
* information in the {@code parentKey} and {@code returnKeySet} left
* unchanged.
*/
int kdbGet(Pointer handle, Pointer returnKeySet, Pointer parentKey);
int kdbGet (Pointer handle, Pointer returnKeySet, Pointer parentKey);

/**
* Set keys in an atomic and universal way.<br >
Expand Down Expand Up @@ -192,12 +191,12 @@ public interface Elektra extends Library {
* in KDB, an error will be set on {@code parentKey} if possible</li>
* </ul>
*/
int kdbSet(Pointer handle, Pointer keySet, Pointer parentKey);
int kdbSet (Pointer handle, Pointer keySet, Pointer parentKey);

/**
* Sets up a contract for use with {@link #kdbOpen(Pointer, Pointer) kdbOpen()}
* that configures the {@code gopts} plugin.
*
*
* @param contractKeySet {@link Pointer} to a valid {@code KeySet} into which
* the contract will be written.
* @param argsSize Size of the {@code args} data.
Expand All @@ -222,210 +221,215 @@ public interface Elektra extends Library {
* <li>{@code -1} on {@code null} pointer passed</li>
* </ul>
*/
int elektraGOptsContractFromStrings(Pointer contractKeySet, long argsSize, String args, long envSize, String env,
Pointer parentKey, @Nullable Pointer goptsConfigKeySet);
int elektraGOptsContractFromStrings (Pointer contractKeySet, long argsSize, String args, long envSize, String env,
Pointer parentKey, @Nullable Pointer goptsConfigKeySet);

// Key methods --------------------------------------------------------------

/**
* Enumeration of argument flags for {@link Elektra#keyNew(String, Object...)}.
*/
enum KeyNewArgumentFlags {
enum KeyNewArgumentFlags
{

/**
* Used as a parameter terminator to {@link Elektra#keyNew(String, Object...)}
*/
KEY_END(0),
KEY_END (0),

/**
* Flag for the key name
*/
KEY_NAME(1),
KEY_NAME (1),

/**
* Flag for the key data
*/
KEY_VALUE(1 << 1),
KEY_VALUE (1 << 1),

/**
* Flag for the key comment
*/
KEY_COMMENT(1 << 3),
KEY_COMMENT (1 << 3),

/**
* Flag if the key is binary
*/
KEY_BINARY(1 << 4),
KEY_BINARY (1 << 4),

/**
* Flag for maximum size to limit value
*/
KEY_SIZE(1 << 11),
KEY_SIZE (1 << 11),

/**
* Flag for metadata
*/
KEY_META(1 << 15);
KEY_META (1 << 15);

private final Integer value;

/**
* @return Integer value recognized by the native library.
*/
public Integer getValue() {
*/
public Integer getValue ()
{
return value;
}

private KeyNewArgumentFlags(int value) {
this.value = Integer.valueOf(value);
private KeyNewArgumentFlags (int value)
{
this.value = Integer.valueOf (value);
}

}

/**
* A practical way to fully create a Key object in one step.<br >
* <br >
* For examples and further particularities, please see the documentation of the
* native library: TODO #3754 link to C API documentation
*
*
* @see #keyDel(Pointer) keyDel()
* @see KeyNewArgumentFlags
*
*
* @param name A valid name to the key, or {@code null} to get a simple
* initialized, but really empty, object.
* @param args Argument flags, each followed by a corresponding value, if appropriate.
* @return <ul>
* <li>A {@link Pointer} to a newly allocated and initialized {@code Key} object on success</li>
* <li>{@code null} on allocation error or if an invalid {@code name} was passed (see {@link #keySetName(Pointer, String) keySetName()</li>
* @param args Argument flags, each followed by a corresponding value, if
* appropriate.
* @return
* <ul>
* <li>A {@link Pointer} to a newly allocated and initialized
* {@code Key} object on success</li>
* <li>{@code null} on allocation error or if an invalid {@code name}
* was passed (see {@link #keySetName(Pointer, String)
* keySetName()}</li>
* </ul>
*/
@Nullable
Pointer keyNew(@Nullable String name, @Nullable Object... args);
@Nullable Pointer keyNew (@Nullable String name, @Nullable Object... args);

Pointer keyDup(Pointer source, int flags);
Pointer keyDup (Pointer source, int flags);

int keyCopy(Pointer dest, Pointer source, int flags);
int keyCopy (Pointer dest, Pointer source, int flags);

int keyClear(Pointer key); // not needed
int keyClear (Pointer key); // not needed

int keyDel(Pointer key);
int keyDel (Pointer key);

int keyIncRef(Pointer key);
int keyIncRef (Pointer key);

int keyDecRef(Pointer key);
int keyDecRef (Pointer key);

int keyGetRef(Pointer key);
int keyGetRef (Pointer key);

/* Meta Info */
int keyRewindMeta(Pointer key);
int keyRewindMeta (Pointer key);

Pointer keyNextMeta(Pointer key);
Pointer keyNextMeta (Pointer key);

Pointer keyCurrentMeta(Pointer key);
Pointer keyCurrentMeta (Pointer key);

int keyCopyMeta(Pointer dest, Pointer source, String metaName);
int keyCopyMeta (Pointer dest, Pointer source, String metaName);

int keyCopyAllMeta(Pointer dest, Pointer source);
int keyCopyAllMeta (Pointer dest, Pointer source);

Pointer keyGetMeta(Pointer key, String metaName);
Pointer keyGetMeta (Pointer key, String metaName);

int keySetMeta(Pointer key, String metaName, String newMetaString);
int keySetMeta (Pointer key, String metaName, String newMetaString);

/* Methods for Making Tests */
int keyCmp(Pointer k1, Pointer k2);
int keyCmp (Pointer k1, Pointer k2);

int keyNeedSync(Pointer key);
int keyNeedSync (Pointer key);

int keyIsBelow(Pointer key, Pointer check);
int keyIsBelow (Pointer key, Pointer check);

int keyIsBelowOrSame(Pointer key, Pointer check);
int keyIsBelowOrSame (Pointer key, Pointer check);

int keyIsDirectlyBelow(Pointer key, Pointer check);
int keyIsDirectlyBelow (Pointer key, Pointer check);

int keyIsBinary(Pointer key);
int keyIsBinary (Pointer key);

int keyIsString(Pointer key);
int keyIsString (Pointer key);

/* Name Manipulation Methods */
String keyName(Pointer key);
String keyName (Pointer key);

int keyGetNameSize(Pointer key);
int keyGetNameSize (Pointer key);

int keyGetName(Pointer key, String returnedName, int maxSize); // not needed
int keyGetName (Pointer key, String returnedName, int maxSize); // not needed

int keySetName(Pointer key, String newname);
int keySetName (Pointer key, String newname);

Pointer keyUnescapedName(Pointer key);
Pointer keyUnescapedName (Pointer key);

int keyGetUnescapedNameSize(Pointer key);
int keyGetUnescapedNameSize (Pointer key);

String keyBaseName(Pointer key); // not implemented
String keyBaseName (Pointer key); // not implemented

int keyGetBaseNameSize(Pointer key); // not implemented
int keyGetBaseNameSize (Pointer key); // not implemented

int keyGetBaseName(Pointer key, String returned, int maxSize); // not needed
int keyGetBaseName (Pointer key, String returned, int maxSize); // not needed

int keySetBaseName(Pointer key, String baseName);
int keySetBaseName (Pointer key, String baseName);

int keyAddBaseName(Pointer key, String baseName);
int keyAddBaseName (Pointer key, String baseName);

/* Value Manipulation Methods */
// byte[] keyValue(Pointer key);
int keyGetValueSize(Pointer key);
int keyGetValueSize (Pointer key);

String keyString(Pointer key);
String keyString (Pointer key);

int keyGetString(Pointer key, String returnedString, int maxSize); // not needed
int keyGetString (Pointer key, String returnedString, int maxSize); // not needed

int keySetString(Pointer key, String newString);
int keySetString (Pointer key, String newString);

// int keyGetBinary(Pointer key, byte[] returnedBinary, int maxSize);
// int keySetBinary(Pointer key, byte[] newBinary, int dataSize);

// KeySet methods -----------------------------------------------------------

Pointer ksNew(int alloc, Object... args);
Pointer ksNew (int alloc, Object... args);

Pointer ksDup(Pointer source);
Pointer ksDup (Pointer source);

int ksCopy(Pointer dest, Pointer source);
int ksCopy (Pointer dest, Pointer source);

int ksClear(Pointer ks); // not needed
int ksClear (Pointer ks); // not needed

int ksDel(Pointer ks);
int ksDel (Pointer ks);

int ksNeedSync(Pointer ks);
int ksNeedSync (Pointer ks);

int ksGetSize(Pointer ks);
int ksGetSize (Pointer ks);

int ksAppendKey(Pointer ks, Pointer toAppend);
int ksAppendKey (Pointer ks, Pointer toAppend);

int ksAppend(Pointer ks, Pointer toAppend);
int ksAppend (Pointer ks, Pointer toAppend);

Pointer ksCut(Pointer ks, Pointer cutpoint);
Pointer ksCut (Pointer ks, Pointer cutpoint);

// TODO #3137 Also elektraKsPopAtCursor should replace the current ksPop. See
// also #3189.
Pointer ksPop(Pointer ks);
Pointer ksPop (Pointer ks);

Pointer elektraKsPopAtCursor(Pointer ks, int cursor);
Pointer elektraKsPopAtCursor (Pointer ks, int cursor);

// deprecated for removal - (forRemoval = true) not set since not all build
// server are using JDK >=9 yet
@Deprecated
int ksRewind(Pointer ks);
@Deprecated int ksRewind (Pointer ks);

Pointer ksHead(Pointer ks);
Pointer ksHead (Pointer ks);

Pointer ksTail(Pointer ks);
Pointer ksTail (Pointer ks);

Pointer ksAtCursor(Pointer ks, int cursor);
Pointer ksAtCursor (Pointer ks, int cursor);

Pointer ksLookup(Pointer ks, Pointer key, int options);
Pointer ksLookup (Pointer ks, Pointer key, int options);

Pointer ksLookupByName(Pointer ks, String name, int options);
Pointer ksLookupByName (Pointer ks, String name, int options);

NativePlugin.ElektraPlugin elektraPluginOpen(String pluginName, Pointer modules, Pointer config, Pointer errorKey);
NativePlugin.ElektraPlugin elektraPluginOpen (String pluginName, Pointer modules, Pointer config, Pointer errorKey);

NativePlugin.ElektraPlugin elektraPluginClose(String pluginName, Pointer errorKey);
NativePlugin.ElektraPlugin elektraPluginClose (String pluginName, Pointer errorKey);
}
Loading

0 comments on commit 9de0cb1

Please sign in to comment.