Documentation on annotations

#1

I know how to get documentation for a c3 type: c3ShowType(MyType).

How do I get documentation for type annotations?

For example I have this type:

@db(versionHistory=true, archive=true)
entity type GenerationFailureEvent schema name ‘STRUCT_GFAILE’

and I would like to know what versionHistory, archive mean and what possible fields exist.

1 Like

#2

All the annotations are actually C3 types too. Try c3ShowType("Ext.Db").

0 Likes

#3

Can you clarify what you mean by c3ShowType("Ext.Db")? I don’t see Ext in the original question as a user defined type, and c3ShowType("Ext") or c3ShowType("Ext.Db") doesn’t work for me.

For my example,

@db(compactType=true, datastore='cassandra', partitionKeyField='parent', persistenceOrder='start',
    persistDuplicates=false, shortId=true, shortIdReservationRange=100000)
entity type FlightMeasurement mixes TimeseriesDataPoint<FlightMeasurementSeries> schema name 'FMEASURE' {
  /// more code, snipped out here
  @ts(treatment='rate')
  kts: int

What would I type to get help on “treatment” in @ts? What would I type to get help on “partitionKeyField” on @db?

0 Likes

#4

c3ShowType(c3Annotation(“Db”)) should work.

0 Likes

#5

Annotations

Intro to annotations

In @romain.juban’s original example, @db(versionHistory=true, archive=true) is an annotation. There is a set of types called “annotation” types, and they can all be applied to type metadata with the @ symbol. There is a base type called Annotation, and what I’m calling the “annotation” types is really just the set of types that are annotated with the @annotation annotation :upside_down_face:.

What did you mean by “Ext.Db” and why doesn’t it work now?

In previous versions of the platform (v6 and below I believe), types were grouped / namespaced in modules. For backwards compatibility reasons and for some time after modules were removed (including platform version 7.2, the latest release at the time of my previous post), types were still assigned a fake module name (e.g., "-type-Metric" for the Metric type), and the c3ShowType utility still allowed you to pass a "moduleName.TypeName" string argument to see type documentation. Several of the annotation types lived in an Ext module, the Db annotation type included. So c3ShowType("Ext.Db") will work in v7.2, but module names must have been officially removed sometime since February.

So how do I see the documentation?

In the C3 console and JavaScript application code, annotation types are not exposed as global variables like regular C3 types are, but rather they are accessible via C3.annotation. For example, if I want to see the documentation for the @ts annotation, c3ShowType(Ts) would not work, but c3ShowType(C3.annotation.Ts) would. The capitalization of annotation types may seem confusing—when applying an annotation, take the annotation type name, downcase the first letter and prepend @ (e.g., C3.annotation.CanonicalTransform --> @canonicalTransform).

There’s also a helper function for locating an annotation type definition by name, which @henry.hsieh mentioned: c3Annotation. It takes a typeName string argument and returns a C3.typesys.type.

Clarification on terminology

Some of the confusion comes from the terminology—“extension” and “annotation” have been used somewhat interchangeably in the past. “extension” comes from the function these types perform (extending metadata), and “annotation” comes from the form in which they’re applied to metadata (@annotation)

The platform team is currently working on clearing up any potential confusion:

“extension” is changing to “annotation” to avoid confusion with “extends.”

Answers to specific questions

(All answers are equivalent)

Documentation for “treatment” in @ts

  • c3ShowType(C3.annotation.Ts)
  • c3ShowFunc(C3.annotation.Ts, 'treatment')
  • c3ShowType(c3Annotation("Ts"))

Documentation for “partitionKeyField” in @db

  • c3ShowType(C3.annotation.Db)
  • c3ShowFunc(C3.annotation.Db, 'partitionKeyField')
  • c3ShowType(c3Annotation("Db"))

Further reading

c3ShowType(C3.annotation.Annotation) for more details on how to write your own annotation type.

5 Likes

How to add a new Annotation?
Is there a way to list all of the different types of annotations that exist?
Documentation for annotations
#6

Thanks! I didn’t see c3Annotation() under the Help menu at the Static Console. I usually navigate to “Help->Commands” to get a list of console commands.

Is c3Annotation() considered a “Console Command”? I’m quite confused, since c3ShowType(c3Annotation) doesn’t pull up any documentation. But c3ShowType(c3Grid) doesn’t pull up any documentation either. Are console commands not Types? Somewhere in the training videos, I was told that “everything is a Type”. I’m scratching my head here…

0 Likes

#7

Thanks, Matt! That was a very nice detailed explanation.

I was told that there are no namespaces besides Tenants and Tags in the C3 Type System. I was also told that when you provision a package, everything is flattened.

What I’m mixed up about is that C3.annotation.Ts implies some sort of hierarchy. Sort of like python and java packages. What is C3? Is that a Type? c3ShowType(C3) doesn’t pull up any documentation.

Update (to others following this thread): Something is very strange in my c3-server environment, because now c3ShowType("Ext.Db") does work to pull up documentation. I don’t know if this is because of some intermediate commands that I ran, or because I had restarted c3-server some point in between. I’m running c3-server version 7.6.0 .

0 Likes

#8

Actually c3Annotation() is a C3 JavaScript Type System utility function, which means you can use it in the C3 Console as well as in JavaScript application code.

Its documentation can be found here: <vanity_url>/static/jsduck/index.html#!/api/global

1 Like

#9

C3 is an object used by the C3 JavaScript Type System to keep track of what came from C3 and what came from other imported JavaScript libraries and the JavaScript runtime. Note that all of the “regular” types (for lack of a better term) actually live in C3.type (e.g., C3.type.Metric). The C3 JavaScript Type System has the ability to expose types as global variables for convenience where possible*, but that’s even a configurable option (see C3 Console --> Tools --> Options --> Expose imported types as global variables), which both the C3 Console and JavaScript action engine do by default.

*JavaScript itself has several standard built-in objects, which are already part of the global scope, so it’s not possible for all types to be defined at the global scope (e.g., C3.type.String === String returns false).

When we say everything is flattened, “everything” means all of the type metadata. At runtime (i.e., after provisioning), C3.type.SomeType is a combination of the original metadata and any alterations made by remixes. However there does seem to be a distinction between “regular” types and annotation types (perhaps to avoid conflicts? C3.type.Db !== C3.annotation.Db); someone on the platform team can probably offer better insight into future plans here.

1 Like

#10

The next step of Romain’s question: what if he didn’t know what annotation to explore?: Is there a way to list all of the different types of annotations that exist?

1 Like