From 47bcc0e46724c0c78c07771bcea3ee97f3d1f6f4 Mon Sep 17 00:00:00 2001
From: Camilo Garcia <ca.garcia2@uniandes.edu.co>
Date: Wed, 30 Oct 2024 13:54:05 -0500
Subject: [PATCH] Improve documentation for findorfs function and NaiveFinder
 algorithm; clarify usage examples and enhance explanations of keyword
 arguments and output.

---
 docs/src/getstarted.md | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/docs/src/getstarted.md b/docs/src/getstarted.md
index 9b230cb..0c2853d 100644
--- a/docs/src/getstarted.md
+++ b/docs/src/getstarted.md
@@ -1,14 +1,17 @@
 ## Finding complete and overlapped ORFIs
 
-The main package function is `findorfs`. Under the hood, the `findorfs` function is an interface for different gene finding algorithms that can be plugged using the `finder` keyword argument. By default it uses the `NaiveFinder` algorithm, which is a simple algorithm that finds all (non-outbounded) ORFIs in a DNA sequence (see the [NaiveFinder](https://camilogarciabotero.github.io/GeneFinder.jl/dev/api/#GeneFinder.NaiveFinder-Union{Tuple{Union{BioSequences.LongDNA{N},%20BioSequences.LongSubSeq{BioSequences.DNAAlphabet{N}}}},%20Tuple{N}}%20where%20N) documentation for more details).
+The main function in the GeneFinder package is `findorfs`, which serves as an interface to various gene-finding algorithms. By default, `findorfs` uses a `NaiveFinder` algorithm, a simple approach that detects all non-outbounded Open Reading Frames (ORFs) in a DNA sequence. You can also specify a different algorithm by setting the `finder` keyword argument. For more details on the NaiveFinder algorithm, see [NaiveFinder](https://camilogarciabotero.github.io/GeneFinder.jl/dev/api/#GeneFinder.NaiveFinder-Union{Tuple{Union{BioSequences.LongDNA{N},%20BioSequences.LongSubSeq{BioSequences.DNAAlphabet{N}}}},%20Tuple{N}}%20where%20N) documentation for more details.
 
 !!! note
-    The `minlen` kwarg in the `NaiveFinder` mehtod has been set to 6nt, so it will catch random ORFIs not necesarily genes thus it might consider `dna"ATGTGA"` -> `aa"M*"` as a plausible ORFI.
+    The minlen keyword argument in `NaiveFinder` is set to a minimum length of 6 nucleotides (nt). As a result, it may identify short ORFs that aren't necessarily genes, such as dna"ATGTGA" producing the amino acid sequence aa"M*".
 
-Here is an example of how to use the `findorfs` function with the `NaiveFinder` algorithm:
+
+## Usage example
+
+Here's an example of using `findorfs` with the `NaiveFinder` algorithm to identify ORFs in a DNA sequence:
 
 ```julia
-using BioSequences, GeneFinder
+julia> using BioSequences, GeneFinder
 
 # > 180195.SAMN03785337.LFLS01000089 -> finds only 1 gene in Prodigal (from Pyrodigal tests)
 seq = dna"AACCAGGGCAATATCAGTACCGCGGGCAATGCAACCCTGACTGCCGGCGGTAACCTGAACAGCACTGGCAATCTGACTGTGGGCGGTGTTACCAACGGCACTGCTACTACTGGCAACATCGCACTGACCGGTAACAATGCGCTGAGCGGTCCGGTCAATCTGAATGCGTCGAATGGCACGGTGACCTTGAACACGACCGGCAATACCACGCTCGGTAACGTGACGGCACAAGGCAATGTGACGACCAATGTGTCCAACGGCAGTCTGACGGTTACCGGCAATACGACAGGTGCCAACACCAACCTCAGTGCCAGCGGCAACCTGACCGTGGGTAACCAGGGCAATATCAGTACCGCAGGCAATGCAACCCTGACGGCCGGCGACAACCTGACGAGCACTGGCAATCTGACTGTGGGCGGCGTCACCAACGGCACGGCCACCACCGGCAACATCGCGCTGACCGGTAACAATGCACTGGCTGGTCCTGTCAATCTGAACGCGCCGAACGGCACCGTGACCCTGAACACAACCGGCAATACCACGCTGGGTAATGTCACCGCACAAGGCAATGTGACGACTAATGTGTCCAACGGCAGCCTGACAGTCGCTGGCAATACCACAGGTGCCAACACCAACCTGAGTGCCAGCGGCAATCTGACCGTGGGCAACCAGGGCAATATCAGTACCGCGGGCAATGCAACCCTGACTGCCGGCGGTAACCTGAGC"
@@ -30,10 +33,12 @@ orfs = findorfs(seq, finder=NaiveFinder) # use finder=NaiveCollector as an alter
  ORFI{NaiveFinder}(695:706, '+', 2)
 ```
 
+## Extracting Sequences from ORFIs
+
 The `ORFI` structure displays the location, frame, and strand, but currently does not include the sequence *per se*. To extract the sequence of an `ORFI` instance, you can use the `sequence` method directly on it, or you can also broadcast it over the `orfs` collection using the dot syntax `.`:
 
 ```julia
-sequence.(orfs)
+julia> sequence.(orfs)
 
 12-element Vector{LongSubSeq{DNAAlphabet{4}}}:
  ATGCAACCCTGA
@@ -50,10 +55,12 @@ sequence.(orfs)
  ATGCAACCCTGA
 ```
 
+## Translating ORFIs to Amino Acid Sequences
+
 Similarly, you can extract the amino acid sequences of the ORFIs using the `translate` function.
 
 ```julia
-translate.(orfs)
+julia> translate.(orfs)
 
 12-element Vector{LongAA}:
  MQP*
@@ -68,4 +75,6 @@ translate.(orfs)
  M*
  MCPTAA*
  MQP*
-```
\ No newline at end of file
+```
+
+This returns a vector of translated amino acid sequences, allowing for easy interpretation of each ORF's potential protein product.
\ No newline at end of file