# Symbol references

Every jdx command takes a symbol reference in Javadoc style. jdx is generous about what it accepts and canonical about what it prints, so any reference it prints can be pasted back into the next command.

## The forms

|Reference|Means|
|---|---|
|`com.google.gson.Gson`|a type|
|`java.util.Map$Entry`, `java.util.Map.Entry`|a nested type (`$` or `.`)|
|`Gson`|a short name — resolved, or exit `2` with candidates|
|`com.google.gson.Gson#toJson`|every overload of a method|
|`com.google.gson.Gson#toJson(Object)`|one overload, simple parameter names|
|`com.google.gson.Gson#toJson(java.lang.Object)`|one overload, qualified parameter names|
|`…#toJson(Object):String`|disambiguated by return type (bridge methods)|
|`…#toJson(Ljava/lang/Object;)Ljava/lang/String;`|an exact JVM descriptor — never ambiguous|
|`com.google.gson.Gson#<init>(...)`|a constructor|
|`java.lang.Integer#MAX_VALUE`|a field|
|`com.google.code.gson:gson:2.14.0/com.google.gson.Gson`|scoped to one Maven artifact|

`::` and `.` are accepted in place of `#`. The last dot-separated segment before the member is
always the class.

**Quote references in a shell.** `#` starts a comment, `(` opens a subshell and `$` expands a
variable — single quotes avoid all three.

## Nested types

Both spellings resolve to the same type, and jdx prints the canonical `$` form:

```console jdx-generated
$ jdx show java.util.Map.Entry
interface java.util.Map$Entry
  public abstract interface Entry
  members: 0 constructors, 15 methods, 0 fields
source: java.base (jrt)
next: jdx members java.util.Map$Entry --inherited
$ jdx show 'java.util.Map$Entry'
interface java.util.Map$Entry
  public abstract interface Entry
  members: 0 constructors, 15 methods, 0 fields
source: java.base (jrt)
next: jdx members java.util.Map$Entry --inherited
```

## Overloads and descriptors

Simple names, qualified names and raw descriptors all select a single overload; fields work the same way:

```console jdx-generated
$ jdx signature 'java.util.HashMap#put(Object, Object)'
signatures of java.util.HashMap#put
  public V put(K key, V value)
source: java.base (jrt)
next: jdx show java.util.HashMap
$ jdx signature 'java.util.HashMap#get(Ljava/lang/Object;)Ljava/lang/Object;'
signatures of java.util.HashMap#get
  public V get(java.lang.Object key)
source: java.base (jrt)
next: jdx show java.util.HashMap
$ jdx signature 'java.lang.Integer#MAX_VALUE'
signatures of java.lang.Integer#MAX_VALUE
  public static final int MAX_VALUE = 2147483647
source: java.base (jrt)
next: jdx show java.lang.Integer
```

## Ambiguity: jdx never guesses

When a reference matches more than one symbol, jdx exits `2` and prints every candidate in its
canonical form. An agent retries with one of them — no reconstruction needed:

```console jdx-generated
$ jdx signature 'com.google.gson.Gson#toJson(Object, Appendable)' --coord com.google.code.gson:gson:2.14.0
signatures of com.google.gson.Gson#toJson
  public void toJson(java.lang.Object src, java.lang.Appendable writer) throws com.google.gson.JsonIOException
warning MULTI_RELEASE_VARIANT: multi-release gson-2.14.0.jar serves version-specific variants for this JDK (21)
source: gson-2.14.0.jar (bytecode)
next: jdx show com.google.gson.Gson
$ jdx body 'com.google.gson.Gson#toJson' --coord com.google.code.gson:gson:2.14.0
ambiguous: 8 candidates for com.google.gson.Gson#toJson
  com.google.gson.Gson#toJson(com.google.gson.JsonElement)
  com.google.gson.Gson#toJson(com.google.gson.JsonElement, com.google.gson.stream.JsonWriter)
  com.google.gson.Gson#toJson(com.google.gson.JsonElement, java.lang.Appendable)
  com.google.gson.Gson#toJson(java.lang.Object)
  com.google.gson.Gson#toJson(java.lang.Object, java.lang.Appendable)
  com.google.gson.Gson#toJson(java.lang.Object, java.lang.reflect.Type)
  com.google.gson.Gson#toJson(java.lang.Object, java.lang.reflect.Type, com.google.gson.stream.JsonWriter)
  com.google.gson.Gson#toJson(java.lang.Object, java.lang.reflect.Type, java.lang.Appendable)
hint: re-run with one of the refs above
[exit 2]
```

## Not found: did you mean

A miss exits `1` with the closest candidates (camel humps, then edit distance, then the same
simple name in other packages):

```console jdx-generated
$ jdx show com.google.gson.JsonParse --coord com.google.code.gson:gson:2.14.0
not found: com.google.gson.JsonParse
did you mean:
  com.google.gson.JsonParser
[exit 1]
```

When you only know a simple name — from a stack trace or a snippet — `jdx resolve` lists every
candidate with its kind and artifact, and several candidates are a success:

```console jdx-generated
$ jdx resolve JsonParser --coord com.google.code.gson:gson:2.14.0
search results for 'JsonParser'
  class com.google.gson.JsonParser  gson-2.14.0.jar
warning MULTI_RELEASE_VARIANT: multi-release gson-2.14.0.jar serves version-specific variants for this JDK (21)
```

## Round-tripping

`parse(print(ref)) == ref` is a tested property: every reference jdx prints — in `members`,
`usages`, `callers`, ambiguity lists, `next:` hints — is accepted verbatim as input.

The full grammar is in the [design specification](https://mohammadmd1383.github.io/jdx/docs/design/#6-symbol-reference-grammar).