[GitHub] [couchdb] jamesbraza opened a new issue #3153: Documentation: misleading $title in Selector Basics section

[GitBox <gi...@apache.org>]

jamesbraza opened a new issue #3153:
URL: https://github.com/apache/couchdb/issues/3153


   ## Description
   
   In the [CouchDB v3.1.0 docs, section 1.3.6.1.1. Selector Basics](https://docs.couchdb.org/en/3.1.0/api/database/find.html#selector-basics), there is an example selector involving `$title`.
   
   > ```json
   > "selector": {
   >   "$title": "Live And Let Die"
   > }
   > ```
   
   However, `$title` is not a valid [CouchDB operator](https://docs.couchdb.org/en/3.1.0/api/database/find.html#operators).   This sample selector implies (to someone not very familiar with CouchDB) that `$title` is a valid identifier (when it isn't).
   
   Furthermore, the sample next lists `fields`:
   
   > ```json
   > "fields": [
   >   "title",
   >   "cast"
   > ]
   > ```
   
   Which lists `title` without a `$`.  This is an inconsistency that also caused me confusion.
   
   ## Expected Behaviour
   
   I think the example should read:
   
   ```json
   "selector": {
     "title": "Live And Let Die"
   },
   "fields": [
     "title",
     "cast"
   ]
   ```
   
   This way:
   - The content of the example is unchanged
   - There is no more confusion around `$title` being an operator
   - There is no more confusion around the field name being `$title` or `title`.
   
   ## Additional Context
   
   Coming from Stack Overflow: [creating a selector for document's name](https://stackoverflow.com/questions/63851309/creating-a-selector-for-documents-name)
   
   If you agree with the above points, I will gladly open a PR to fix this issue.
   
   It seems the `$title` hiccup is also found in section [1.3.6.1.7. Combination Operators](https://docs.couchdb.org/en/3.1.0/api/database/find.html#combination-operators), it should also probably be changed there as well.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org