docs: cleanup function reference guide

docs/src/functions.md

@@ -1,7 +1,14 @@
 ```@meta
 CurrentModule = AwkwardArray
 ```
-## List of [`Content`](@ref) functions
+
+# Functions
+
+```@contents
+Pages = ["functions.md"]
+```
+
+## Built-in functions
 
 Every [`Content`](@ref) subclass has the following built-in functions:
 
@@ -15,7 +22,24 @@ Every [`Content`](@ref) subclass has the following built-in functions:
 * [`Base.append!`](@ref)
 * [`Base.show`](@ref)
 
-They also have the following functions for manipulating and checking structure:
+```@docs
+Base.length
+Base.size
+Base.firstindex
+Base.lastindex
+Base.getindex
+Base.iterate
+Base.eltype
+Base.:(==)
+Base.push!
+Base.append!
+Base.show
+Base.keys
+```
+
+## Manipulating and checking structure
+
+Every [`Content`](@ref) subclass has the following functions for manipulating and checking structure:
 
 * [`AwkwardArray.parameters_of`](@ref) gets all parameters
 * [`AwkwardArray.has_parameter`](@ref) returns true if a parameter exists
@@ -24,24 +48,52 @@ They also have the following functions for manipulating and checking structure:
 * [`AwkwardArray.copy`](@ref) shallow-copy of the array, allowing properties to be replaced
 * [`AwkwardArray.is_valid`](@ref) verifies that the structure adheres to Awkward Array's protocol
 
-They have the following functions for filling an array:
+```@docs
+parameters_of
+has_parameter
+get_parameter
+with_parameter
+copy
+is_valid
+```
+
+## Filling an array
+
+Every [`Content`](@ref) subclass has the following functions for filling an array:
 
 * [`AwkwardArray.end_list!`](@ref): closes off a [`ListType`](@ref) array ([`ListOffsetArray`](@ref), [`ListArray`](@ref), or [`RegularArray`](@ref)) in the manner of Python's [ak.ArrayBuilder](https://awkward-array.org/doc/main/reference/generated/ak.ArrayBuilder.html) (no `begin_list` is necessary)
 * [`AwkwardArray.end_record!`](@ref) closes off a [`RecordArray`](@ref)
 * [`AwkwardArray.end_tuple!`](@ref) closes off a [`TupleArray`](@ref)
-* [`AwkwardArray.push_null!`](@ref) pushes a missing value onto [`OptionType`](@ref) arrays (`IndexedOptionArray`](@ref) [`ByteMaskedArray`](@ref) [`BitMaskedArray`](@ref) or [`UnmaskedArray`](@ref))
+* [`AwkwardArray.push_null!`](@ref) pushes a missing value onto [`OptionType`](@ref) arrays ([`IndexedOptionArray`](@ref) [`ByteMaskedArray`](@ref) [`BitMaskedArray`](@ref) or [`UnmaskedArray`](@ref))
 * [`AwkwardArray.push_dummy!`](@ref) pushes an unspecified value onto the array (used by [`ByteMaskedArray`](@ref) and [`BitMaskedArray`](@ref) which need to have a placeholder in memory behind each `missing` value)
 
+```@docs
+end_list!
+end_record!
+end_tuple!
+push_null!
+push_dummy!
+```
+## Selecting fields
+
 [`RecordArray`](@ref)and [`TupleArray`](@ref) have the following for selecting fields (as opposed to rows):
 
 * [`AwkwardArray.slot`](@ref) gets a [`RecordArray`](@ref)or [`TupleArray`](@ref) field, to avoid conflicts with [`Base.getindex`](@ref) for `TupleArrays` (both use integers to select a field)
 * [`AwkwardArray.Record`](@ref) scalar representation of an item from a [`RecordArray`](@ref)
 * [`AwkwardArray.SlotRecord`](@ref) scalar representation of an item from a [`TupleArray`](@ref)(note: not the same as `Base.Tuple`)
 
+```@docs
+AwkwardArray.slot
+```
+
+## Specializations
+
 [`UnionArray`](@ref)has the following for dealing with specializations:
 
 * [`AwkwardArray.Specialization`](@ref) selects a [`UnionArray`](@ref)specialization for [`push!`](@ref) [`append!`](@ref) etc.
 
+## Convertion
+
 Finally, all [`Content`](@ref)subclasses can be converted with the following:
 
 * [`AwkwardArray.layout_for`](@ref) returns an appropriately-nested [`Content`](@ref)type for a given Julia type (`DataType`)
@@ -50,13 +102,46 @@ Finally, all [`Content`](@ref)subclasses can be converted with the following:
 * [`AwkwardArray.from_buffers`](@ref) constructs an Awkward Array from a Form (JSON), length, and buffers for zero-copy passing from Python
 * [`AwkwardArray.to_buffers`](@ref) deconstructs an Awkward Array into a Form (JSON), length, and buffers for zero-copy passing to Python
 
+```@docs
+AwkwardArray.layout_for
+AwkwardArray.from_iter
+AwkwardArray.to_vector
+AwkwardArray.to_vector_or_scalar
+AwkwardArray.from_buffers
+AwkwardArray.to_buffers
+```
 
-## Array functions
+## Arrays of Stings
+
+```@docs
+ByteStringOffsetArray
+ByteStringArray
+ByteStringRegularArray
+StringArray
+StringOffsetArray
+StringRegularArray
+```
+
+## Utilities
+
+```@docs
+AwkwardArray.isprimitive
+AwkwardArray.default_buffer_key
+AwkwardArray.compatible
+AwkwardArray.check_primitive_type
+```
 
-```@autodocs
-Modules = [AwkwardArray]
-Public = true
-Order = [:function]
+## Private functions
+
+```@docs
+AwkwardArray._alternate
+AwkwardArray._get_buffer
+AwkwardArray._get_index
+AwkwardArray._horizontal
+AwkwardArray._to_buffers!
+AwkwardArray._to_buffers_index
+AwkwardArray._to_buffers_parameters
+AwkwardArray._vertical
 ```
 
 # Index

docs/src/getting_started.md

@@ -6,6 +6,13 @@ Let's assume that both Python and Julia are installed.
 
 It is recommended to use [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html) virtul environment.
 
+!!! note
+    If Julia is not install it is recomended to install it from a conda-forge channel:
+
+    ```python
+    conda install -c conda-forge julia
+    ```
+
 ## Using Julia Awkward Arrays from Python
 
  - To install [Awkward Array](https://github.com/scikit-hep/awkward) Python package:

src/all_implementations.jl

@@ -984,7 +984,7 @@ end
         parameters::Parameters = Parameters(),
     ) where {INDEX<:IndexBig} where {CONTENT<:Content} where {BEHAVIOR}
 
-Constructor of a [`ListArray`](@ref) with default parameters, initializing the starts, stops and content with default values.
+Constructor of a `ListArray` with default parameters, initializing the starts, stops and content with default values.
 """
 ListArray{INDEX,CONTENT,BEHAVIOR}(;
     parameters::Parameters = Parameters(),
@@ -997,7 +997,7 @@ ListArray{INDEX,CONTENT,BEHAVIOR}(;
         behavior::Symbol = :default,
     ) where {INDEX<:IndexBig} where {CONTENT<:Content}
 
-Constructor of a [`ListArray`](@ref) with default parameters, initializing the starts, stops, content and behavior with default values.
+Constructor of a `ListArray` with default parameters, initializing the starts, stops, content and behavior with default values.
 """
 ListArray{INDEX,CONTENT}(;
     parameters::Parameters = Parameters(),
@@ -1015,7 +1015,7 @@ ListArray{INDEX,CONTENT}(;
         behavior::Union{Unset,Symbol} = Unset(),
     ) where {INDEX1<:IndexBig,INDEX2<:IndexBig,CONTENT1<:Content,CONTENT2<:Content,BEHAVIOR}
 
-Copy of a [`ListArray`](@ref).
+Copy of a `ListArray`.
 """    
 function copy(
     layout::ListArray{INDEX1,CONTENT1,BEHAVIOR};
@@ -1695,7 +1695,16 @@ end
         byte_parameters::Parameters = Parameters(),
     ) where {INDEX<:IndexBig}
 
-[`ListType`](@ref) with `behavior` = `:bytestring`.
+The function that constructs a specialized array type for handling byte strings with specific offsets.
+
+ - `offsets`: This is an array of indices (`INDEX`) which determines where each string starts within the byte array.
+ - `data`: This is a vector of `UInt8` (unsigned 8-bit integers), representing the raw bytes of the strings.
+ - `parameters`: Optional parameters for configuring the `ListOffsetArray`.
+ - `byte_parameters`: Optional parameters specifically for the `PrimitiveArray` holding the byte data.
+ - `INDEX<:` Ensures that offsets is a subtype of `IndexBig`, which typically implies a larger indexing type suitable for big data.
+
+!!! note
+    It is a [`ListType`](@ref) with `behavior` = `:bytestring`.
 """
 ByteStringOffsetArray(
     offsets::INDEX,
@@ -1714,6 +1723,8 @@ ByteStringOffsetArray(
         parameters::Parameters = Parameters(),
         byte_parameters::Parameters = Parameters(),
     )
+
+A default constructor that initializes an empty `ByteStringOffsetArray`.
 """
 ByteStringOffsetArray(;
     parameters::Parameters = Parameters(),
@@ -1733,6 +1744,8 @@ ByteStringOffsetArray(;
         parameters::Parameters = Parameters(),
         byte_parameters::Parameters = Parameters(),
     ) where {INDEX<:IndexBig}
+
+The `ByteStringArray` function constructs a specialized array type for handling byte strings, similar to `ByteStringOffsetArray`, but it uses separate `starts` and `stops` indices rather than a single `offsets` array.
 """
 ByteStringArray(
     starts::INDEX,
@@ -1753,6 +1766,8 @@ ByteStringArray(
         parameters::Parameters = Parameters(),
         byte_parameters::Parameters = Parameters(),
     )
+
+A default constructor that initializes an empty `ByteStringArray`.
 """
 ByteStringArray(;
     parameters::Parameters = Parameters(),
@@ -2854,7 +2869,7 @@ IndexedOptionArray{INDEX,CONTENT}(;
         BEHAVIOR,
     }
 
-Copy of an [`IndexedOptionArray`](@ref), potentially with some modifications to its fields.
+Copy of an `IndexedOptionArray`, potentially with some modifications to its fields.
 """
 function copy(
     layout::IndexedOptionArray{INDEX1,CONTENT1,BEHAVIOR};