From fe6141ced711647a34b5454e7d60cd3d2ae9b341 Mon Sep 17 00:00:00 2001
From: Leandro Martinez <lmartine@unicamp.br>
Date: Wed, 29 Nov 2023 22:01:58 -0300
Subject: [PATCH] improve general selection docs

---
 docs/src/selections.md | 34 ++++++++++++++++++++++++++--------
 1 file changed, 26 insertions(+), 8 deletions(-)

diff --git a/docs/src/selections.md b/docs/src/selections.md
index 29b123cc..29a94bed 100644
--- a/docs/src/selections.md
+++ b/docs/src/selections.md
@@ -83,23 +83,41 @@ indexes = selindex(atoms,"protein and name CA")
 !!! note
     All indexing is 1-based. Thus, the first atom of the structure is atom 1.
 
-## Use Julia anonymous functions directly
+## Use Julia functions directly
 
-Selections can be done using Julia anonymous functions directly, providing a greater
+Selections can be done using Julia functions directly, providing a greater
 control over the selection and, possibly, the use of user defined selection 
 functions. For example:
 
 ```julia
-atoms = select(atoms, by = atom -> atom.x < 10.)
-
+myselection(atom) = (atom.x < 10.0 && atom.resname == "GLY") || (atom.name == "CA") 
+atoms = select(atoms, by = myselection)
 ```
-With that, selections can become really complex, as:
+or, for example, using Julia anonymous functions
 ```julia
-sel = atom -> (atom.x < 10. && atom.resname == "GLY") || (atom.name == "CA") 
-atoms = select(atoms, by = sel )
-
+select(atoms, by = at -> isprotein(at) && name(at) == "O" && atom.x < 10.0)
 ```
 
+The only requirement is that the function defining the selection receives an `PDBTools.Atom` as
+input, and returns `true` or `false` depending on the conditions required for the atom.
+
+!!! note
+    The macro-keywords described in the previous section can be used within 
+    the Julia function syntax, but the function names start with `is`. For example:
+    ```julia
+    select(atoms, at -> isprotein(at) && resnum(at) in [ 1, 5, 7 ])
+    ```
+    Thus, the macro selection functions are:
+    `iswater`, 
+    `isprotein`,     `isbackbone`,    `issidechain`,
+    `isacidic`,      `isbasic`,                  
+    `isaliphatic`,   `isaromatic`,               
+    `ischarged`,     `isneutral`,                
+    `ispolar`,       `isnonpolar`,               
+    and `ishydrophobic`.                          
+    
+
+
 ## Iterate over residues (or molecules)
 
 The `eachresidue` iterator allows iteration over the resiudes of a structure (in PDB files distinct molecules are associated to different residues, thus this iterates similarly over the molecules of a structure). For example: