Docs: Add clarifications for LIST data type DDL specifications (hashtag2823)

[vikramsubramanian]

Thanks for the great work on this project! I wanted to open a suggestion for [documentation surrounding the LIST data type]( which I thought might help clarify usage.

Currently the beginning of this page reads:

Kùzu supports two `LIST` data types: variable-size list `VAR-LIST` and fixed-size `FIXED-LIST`.

A `VAR-LIST` type can contain arbitrary number of values with the same type.

A `FIXED-LIST` type can contain fixed number of values with the same numerical type.

This could be improved with an additional statement concerning the use of other datatypes (any data type?) before the brackets in DDL. Additionally, it looked like there was a typo concerning the FIXED-LIST content ("same numerical type", not certain but it seems like this should be "same type").

Kùzu supports two LIST data types: variable-size list `VAR-LIST` and fixed-size `FIXED-LIST.`

`LIST` data types include values of a single data type.
The data type of values within a `LIST` is declared before a set of brackets in DDL.
For example, `STRING[]` declares a `LIST` of string values.

A `VAR-LIST` type can contain arbitrary number of values with the same type.

A `FIXED-LIST` type can contain fixed number of values with the same type.

It might be that the following content is inferred from other, more comprehensive documentation about the DDL grammar. Please don't hesitate to correct or link to a better resource instead of the below. Thank you! )

[mayil-ai[bot]]

Summary: The documentation for the LIST data type DDL specifications needs to be clarified and improved.

Possible Solution

To address the issue described, follow these steps:

• Update the documentation to correct the typo and clarify the usage of LIST types in DDL. Replace "same numerical type" with "same type" and provide clear examples for declaring LIST types.
• Ensure that the documentation reflects the correct syntax for VAR-LIST and FIXED-LIST as per the hypothesized documentation provided.
• Verify that the code snippets related to FixedListTypeInfo and VarListTypeInfo in types.h and their usage in value_vector.cpp and data_type_test.cpp are consistent with the updated documentation.
• If there are any discrepancies between the documentation and the implementation, update the code to match the documentation or vice versa, depending on which is correct.
• Add tests in data_type_test.cpp and other relevant test files to cover the corrected documentation and any code changes made to ensure that VAR-LIST and FIXED-LIST behave as expected.
• Review the DDL grammar specifications to ensure that they allow for the correct declaration of LIST types as per the updated documentation.
• After making changes, perform a thorough code review and testing to ensure that the issue is resolved without introducing new bugs.

Code snippets to check

• src/include/common/types/types.h

  This file contains the definitions and comments related to the LIST data types, which are directly relevant to the documentation issue.