From 18b7df9f49d9d4125cc1842c9d8ddb134d8a58cf Mon Sep 17 00:00:00 2001 From: a4z Date: Tue, 7 Nov 2023 20:23:19 +0100 Subject: [PATCH 1/3] Add documentatio for PR 156 --- docs/idl.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 46 insertions(+), 6 deletions(-) diff --git a/docs/idl.md b/docs/idl.md index 7fb3714c..99a40b88 100644 --- a/docs/idl.md +++ b/docs/idl.md @@ -153,7 +153,7 @@ The available data types for a record, argument, or return value, and their equi ✱ *Primitives will be boxed in Java and Objective-C.* -Additional possible data types are: +Additional possible data types are: - Enumerations / Flags - Other record types. This is generated with a by-value semantic, i.e. the copy method will @@ -164,7 +164,7 @@ Additional possible data types are: An IDL file can contain 4 kinds of declarations: enums, flags, records, and interfaces. * [**Enums**](#enums) become C++ enum classes, Java enums, ObjC `NS_ENUM`s, Python `IntEnum`s, or C# `System.Enum`s. -* [**Flags**](#flags) become C++ enum classes with convenient bit-oriented operators, Java enums with `EnumSet`, +* [**Flags**](#flags) become C++ enum classes with convenient bit-oriented operators, Java enums with `EnumSet`, ObjC `NS_OPTIONS`, Python `IntFlag`s, or C# `System.Enum`s with the [`[Flags]` Attribute](https://docs.microsoft.com/en-us/dotnet/api/system.flagsattribute?view=net-5.0). * [**Records**](#records) are pure-data value objects. * [**Interfaces**](#interfaces) are objects with defined methods to call (in C++, passed by `shared_ptr`). Djinni @@ -198,7 +198,7 @@ my_flags = flags { Flags are translated to C++ `enum class`es with underlying type `unsigned` and a generated set of overloaded bitwise operators for convenience, ObjC `NS_OPTIONS` with underlying type `NSUInteger`, -Java `EnumSet<>`, Python `IntFlag`, and C# `System.Enum`s with the [`[Flags]` Attribute](https://docs.microsoft.com/en-us/dotnet/api/system.flagsattribute?view=net-5.0). +Java `EnumSet<>`, Python `IntFlag`, and C# `System.Enum`s with the [`[Flags]` Attribute](https://docs.microsoft.com/en-us/dotnet/api/system.flagsattribute?view=net-5.0). Contrary to the above enums, the enumerants of flags represent single bits instead of integral values. In the above example the elements marked with `none` and `all` are given special meaning. In C++, @@ -286,7 +286,7 @@ produces code allowing an interface implemented in C++ to be transparently used Java Python or C# and vice versa. #### Special Methods for C++ Only -`+c` interfaces (implementable only in C++) can have methods flagged with the special keywords const and static which +`+c` interfaces (implementable only in C++) can have methods flagged with the special keywords const and static which have special effects in C++: special_methods = interface +c { @@ -295,12 +295,12 @@ have special effects in C++: } - `const` methods will be declared as const in C++, though this cannot be enforced on callers in other languages, which lack this feature. -- `static` methods will become a static method of the C++ class, which can be called from other languages without an object. +- `static` methods will become a static method of the C++ class, which can be called from other languages without an object. This is often useful for factory methods to act as a cross-language constructor. #### Exception Handling When an interface implemented in C++ throws a `std::exception`, it will be translated to a -`java.lang.RuntimeException` in Java, an `NSException` in Objective-C, a `RuntimeError` in Python, +`java.lang.RuntimeException` in Java, an `NSException` in Objective-C, a `RuntimeError` in Python, or a `System.Exception` in C#. The `what()` message will be translated as well. @@ -327,3 +327,43 @@ will be `RecordWithConst::CONST_VALUE` in C++, `RecordWithConst.CONST_VALUE` in If comments are placed on top or inside a type definition, they will be converted to Javadoc / Doxygen compatible comments in the generated Java, C++, Objective-C and C++/CLI interfaces, or a Python docstring. + +## Deprecation Comments + +It's possible to add deprecation comments to IDL types and methods. + +The comment in the IDL file has to start the `# @deprecated reason/hing message` . + +This will generate the corresponding deprecation annotation in the target language. + +```idl +# @deprecated Use someother interface +my_interface = interface +c { .... } +``` + +Such a comment will generate code like + +C++: + +```cpp +class [[deprecated("reason/hing message")]] MyInterface { ... } +``` + +Java: + +```java +/** + * interface comment + * + * @deprecated Use someother interface + */ +@Deprecated +public abstract class MyInterface { ... } +``` + +Objective-C: + +```objc + __deprecated_msg("Use someother interface") +@interface ITMyInterface : NSObject +``` From b7ddcd24b256022ef16a367868b53f94be0ab7ae Mon Sep 17 00:00:00 2001 From: Harald Date: Fri, 10 Nov 2023 10:52:41 +0100 Subject: [PATCH 2/3] Fix typo --- docs/idl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/idl.md b/docs/idl.md index 99a40b88..a7489371 100644 --- a/docs/idl.md +++ b/docs/idl.md @@ -332,7 +332,7 @@ Python docstring. It's possible to add deprecation comments to IDL types and methods. -The comment in the IDL file has to start the `# @deprecated reason/hing message` . +The comment in the IDL file has to start the `# @deprecated reason/hint message` . This will generate the corresponding deprecation annotation in the target language. From 732b325544c7dba463a2fbecd93f0f6e64c6eb78 Mon Sep 17 00:00:00 2001 From: Harald Date: Fri, 10 Nov 2023 10:53:03 +0100 Subject: [PATCH 3/3] Change writing of word --- docs/idl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/idl.md b/docs/idl.md index a7489371..8db14200 100644 --- a/docs/idl.md +++ b/docs/idl.md @@ -337,7 +337,7 @@ The comment in the IDL file has to start the `# @deprecated reason/hint message` This will generate the corresponding deprecation annotation in the target language. ```idl -# @deprecated Use someother interface +# @deprecated Use some_other interface my_interface = interface +c { .... } ```