Better documentation

[tmssngr]

Please rework the documentation before approaching v1.0. Currently, it looks a little bit unstructured, sparse in some areas, and it's not very clear at what page to find the answer for a certain problem. It should not assume too much experience with Go or Rust.

Example: I find this documentation easier to understand: https://flint-lang.github.io/wiki/v0.4.0-core/beginners_guide.html and navigate (with the side menu)

I would find it useful to have a clear structure:

• hello world program explained, simple lisette.toml
• basic structure of a source code file, supported comments
• variable declarations, mut
• operators
• primitive types
• strings, string interpolation
• casting
• arrays, slices (how they are declared as variable, how they are inferred, how as parameter)
• structs
• tuples
• enums
• refs
• optionals, nil-safety
• result types, ? and try
• control flow
  • if, last expression is value of block
  • if let
  • match
  • while
  • for
• functions, return values
• struct-associated methods, interfaces
• generics
• function types, lambdas
• unit testing
• modules, best-practice for structuring code, directory structure
• interaction with Go code
  • imports, lisette.toml
  • how to access Go code, different (return) types
• additional features of lis

I have made the experience that when writing the documentation less logical things become more obvious. Hence I would not do it as last step before the release, but would collect feedback regarding the syntax before it is carved in stone with v1.0.

[ivov]

Indeed! The docs need more love. Based on this framework, today's docs are purely a reference, and there are no tutorials to learn by doing. A dedicated docs site would be nice as well. It's on my list, but at low priority - still a mighty long road to v1.0.

In the meantime, feel free to report any spots that you find confusing.

[enquora]

One of the advantages of using Rust syntax is that every inference engine has been trained on similar code.
Every one of the frontier models has proven effective at explanations and code generation when told "Lisette is a language in the ML family using Rust syntax - which compiles to raw Go".

Given any experience with ADTs and structural pattern matching, Claude, Gemini, ChatGPT, DeepSeek, Qwen and GLM have all proven effective at building up or auditing existing code and explaining/auditing fragments. They are equally capable of explaining concepts - although all the prominent ones seem to be developing an irritating personality.

Even without any background in Rust (but a firm foundation in OCaml), it has been possible to build an infrastructure grade compiler using just the source code and inference engines as references - to learn the language and move the project along whenever velocity slowed. This is from a standing start, in a little over four months, and includes a huge amount of code archeology wrt the legacy system on which it is modelled. The syntax becomes all but inevitable from the perspective of the core language imperatives: expression oriented, H-M type system, ADTs, and structural pattern matching.

ymmv. This does not help if one learns from the outside-in, top-down, of course.

[tmssngr]

I'd need information how to create a slice out of an array. I've tried buffer[5..5 + data_count], but got the error

  ✕ Type mismatch
     ╭─[src/main.lis:278:39]
 277 │
 278 │         let written = match self.file.Write(self.buffer[5..5 + data_count]) {
     ·                                             ─────┬─────
     ·                                                  ╰── expected Slice, found Array<byte, 133>
 279 │             Ok(w) => w,
     ╰────
  help: Call .to_slice() to copy the elements into a new slice before range indexing · code: [infer.range_index_not_slice]

https://github.com/ivov/lisette/blob/main/docs/reference/02-types.md does not mention to_slice().

[ivov]

The prelude is currently documented in the CLI. For now please use lis doc

$ lis doc Array

  type Array<T, N>
    A fixed-size, indexable sequence of elements. Equivalent to Go's [N]T.

      let xs: Array<int, 3> = [1, 2, 3]
      let ys = Array.new<int, 256>()
      let n = xs.length()
      let copy = xs.to_slice()

    fn new() -> Array<T, N>
      Creates an array of N zero values.

    fn length(self) -> int
      Returns the size of the array.

    fn get(self, index: int) -> Option<T>
      Returns the element at index, or None if out of bounds.

    fn to_slice(self) -> Slice<T>
      Copies the elements into a new slice.

As part of the docs site work, I'm planning to include the prelude so it's more discoverable.

[tmssngr]

BTW, is there also a array.to_slice(start) and array.to_slice(start, end) or should that be written like array.to_slice()[start..] or array.to_slice()[start..start+end]? IMHO the latter will create two slice instances, right?

[ivov]

Not quite, there is no need for an overload here. A subrange of a Slice is itself a Slice over the same memory, so buffer[5..5 + data_count] already carries both the offset and the length.

Mind you, I believe your buffer should be a Slice, not an Array.

let buffer = Slice.make<byte>(133)

Slice<byte> crosses to Go as []byte, which is what Read and Write take, so it passes through and indexes directly, with no to_slice() anywhere. Array<T, N> crosses as [N]T with value semantics, and the only way into []byte is to_slice(), which copies. Keep Array for values whose size is part of their identity, like a 32-byte digest.

The challenge here is that the docs assume familiarity with Go, as you mentioned above. I'll keep this in mind when I rework them.

[tmssngr]

Yes, my lack of deep Go knowledge seems to be the root of many troubles I'm facing.