Documention and deprecation

Documenting states and mutations

You can document your states and fields by adding a doc attribute to their definition. The doc attribute should contain a string that describes the purpose of the state or field.

The doc attribute can be any kind of string, including:

• A single line of text, using either single (') or double quotes (")
• A multi-line string, using triple quotes (""")

Here's an example of how to use the doc attribute to document a state and its fields:

"""
This state is used to represent a user.
"""
state User {
  """
  The user's first name.
  """
  firstName: String = 1
 
  """
  The user's last name.
  """
  lastName: String = 2
}

All the documentation you add to your states and fields will be included in the generated code from the schema compiler, and will help you and your team understand the purpose of each state and field.

Documenting mutations

You can document your mutations by adding a doc attribute to their definition. The doc attribute should contain a string that describes the purpose of the mutation. It's also possible to document the arguments of a mutation.

"""
This mutation is used to create a new user.
"""
create(
  """
  The user's first name.
  """
  firstName: String,
 
  """
  The user's last name.
  """
  lastName: String
): User

Either states

It's also possible to document either states. This is useful when you want to document the possible states the user should expect when using an either state.

"""
All the users that can log in to the system.
"""
either User: RegisteredUser | ActiveUser

Deprecating in Neuledge

In Neuledge, it is generally not recommended to deprecate fields directly. Instead, it's better to create a new state that replaces the deprecated state and switch to it. Neuledge can help you manage all of the states in parallel, and you will be able to remove outdated states over time.

To deprecate a state, you can use the @deprecated(reason: "explanation") decorator. This decorator can be applied to a state, eithers or a mutation, but also to a field or a mutation argument. This will signal to other developers that this particular item is no longer recommended for use. The reason argument is optional but it's recommended to provide a clear reason why the item is being deprecated.

Here's an example of how to deprecate a state:

state User from LegacyUser {
  @unique email: Email = 1
}
 
@deprecated(reason: "Use the User state instead.")
state LegacyUser {
  @id(auto: 'increment') id: Integer = 1
  firstName: String = 2
  lastName: String = 3
  @unique email: String = 4
}
 

In this example, we're deprecating the "LegacyUser" state and replacing it with the "User" state. The "User" state is a copy of the "LegacyUser" state, but with the "email" field changed to use the Email type instead of a String.

Please note that in Neuledge there is no problem to rename states names and fields. As long as you keep the types and the field indexes the same, Neuledge will be able to handle the change without any issues.