Add SymbolInformation.enclosing_symbol (#164)

* Add `SymbolInformation.enclosing_symbol`

Towards #154

Previously, it was not possible to determine the enclosing symbol of a
local because the syntax for local symbols has no hierarchy (unlike
global symbols). This PR closes the gap by adding a field
`SymbolInformation.enclosing_symbol` to allow documenting the "parent"
or "owner" of a local symbol.

* Add example for enclosing_symbol

* Regenerate bindings, and gitignore Haskell output

Author: olafurpg

.gitignore

@@ -26,3 +26,4 @@ cmd/scip
 
 # Dependency directories (remove the comment below to include it)
 # vendor/
+dist-newstyle/

bindings/go/scip/scip.pb.go

@@ -327,6 +327,24 @@ message SymbolInformation {
   // while other fields such as `Documentation.occurrences` can be optionally
   // included to support hyperlinking referenced symbols in the signature.
   Document signature_documentation = 7;
+  // (optional) The enclosing symbol if this is a local symbol.  For non-local
+  // symbols, the enclosing symbol should be parsed from the `symbol` field
+  // using the `Descriptor` grammar.
+  //
+  // The primary use-case for this field is to allow local symbol to be displayed
+  // in a symbol hierarchy for API documentation. It's OK to leave this field
+  // empty for local variables since local variables usually don't belong in API
+  // documentation. However, in the situation that you wish to include a local
+  // symbol in the hierarchy, then you can use `enclosing_symbol` to locate the
+  // "parent" or "owner" of this local symbol. For example, a Java indexer may
+  // choose to use local symbols for private class fields while providing an
+  // `enclosing_symbol` to reference the enclosing class to allow the field to
+  // be part of the class documentation hierarchy. From the perspective of an
+  // author of an indexer, the decision to use a local symbol or global symbol
+  // should exclusively be determined whether the local symbol is accessible
+  // outside the document, not by the capability to find the enclosing
+  // symbol.
+  string enclosing_symbol = 8;
 }