Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs #24

Merged
merged 4 commits into from
Jan 20, 2021
Merged

Update docs #24

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
154add9
Update docs
a4z Jan 20, 2021
8d1a3f9
strong text for important note
a4z Jan 20, 2021
868bf0b
Identifiers text improvement
a4z Jan 20, 2021
73adb65
Remove empty line
a4z Jan 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 42 additions & 2 deletions docs/cli-usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ djinni \
| `--jni-include-prefix <prefix>` | The prefix for #includes of JNI header files from JNI C++ files. |
| `--jni-include-cpp-prefix <prefix>` | The prefix for #includes of the main header files from JNI C++ files. |
| `--jni-namespace ...` | The namespace name to use for generated JNI C++ classes. |
| `--jni-base-lib-include-prefix ...` | The JNI base library's include path, relative to the JNI C++ classes. |
| `--jni-base-lib-include-prefix ...` | The JNI base support library's include path (default: djinni/jni/). |

### Objective-C

Expand All @@ -106,7 +106,7 @@ djinni \
| `--cpp-extended-record-include-prefix <prefix>` | The prefix path for #include of the extended record C++ header (`.hpp`) files |
|`--objc-extended-record-include-prefix <prefix>` | The prefix path for #import of the extended record Objective-C header (`.h`) files |
|`--objcpp-namespace <prefix>` | The namespace name to use for generated Objective-C++ classes. |
|`--objc-base-lib-include-prefix ...` | The Objective-C++ base library's include path, relative to the Objective-C++ classes. |
|`--objc-base-lib-include-prefix ...` | The Objective-C base support library's include path (default: djinni/objc/). |

### Yaml Generation

Expand Down Expand Up @@ -150,6 +150,46 @@ Identifier styles (ex: `FooBar`, `fooBar`, `foo_bar`, `FOO_BAR`, `m_fooBar`)
| `--ident-objc-type-param ...` |
| `--ident-objc-local ...` |
| `--ident-objc-file ...` |
| |
a4z marked this conversation as resolved.
Show resolved Hide resolved

The _Identifier Style_ is a text conversion hint on how to generate names from the djinni idl file.

Example:
The djinni idl for an enum

```
SomeEnum = enum {
Value;
}
```

transforms per default to the following Java code

```
public enum SomeEnum {
VALUE,
;
}
```
As you see, _VALUE_ is now in upper case letters.

If you use `--ident-java-enum foo_bar` then _Value_ will not be transformed into upper case and the following Java code will be generated.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is so weird 🙈
If changing the Identifier names would not potentially break so many builds I'd prefer more speaking names for them:

  • camelCase
  • TrainCase
  • snake_case
  • none <== This is what foo_bar currently is.
  • ...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about renaming them? This just came to my mind a few days ago. I don't see it in the scope of this PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might still be a breaking change.
we could add none as a keyword to start a smooth transition process ....

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just want to talk with you about this on a theoretical basis. :P I'm aware that this is a major breaking change.


```
public enum SomeEnum {
Value,
;
}
```

This way you can adopt code generation to some extend to your existing coding style.


The best way to find out how that works is playing around with different values for different identifier options.

**If you wish not text transformation to happen, use the `foo_bar` style.**

!!! note

Some defaults have been set while back, that, for example enum names are transformed to uppercase letters.
At the moment we do not want to change that behavior, but please be aware that we think the default should always be no text transformation for all settings.
a4z marked this conversation as resolved.
Show resolved Hide resolved