Standard library documentation #1

BenjaminNavarro · 2020-04-11T15:17:50Z

Creating a PR now so that I can get early feedback.

So far, I just created the pages listed in Feral-Lang/Feral#8. I'll start enumerating what's available in each module and then we can see what's the best way to organize it

BenjaminNavarro · 2020-04-11T15:30:46Z

Preview available here https://benjaminnavarro.github.io/Book/12-standard-library.html

src/12-standard-library.md

Electrux · 2020-04-11T15:54:16Z

Looks great! 😁
Just added a little comment.

BenjaminNavarro · 2020-04-11T18:23:23Z

I started with the IO module. Could you tell me if you like it like this?

I'm still unsure about the presentation of the functions signature. Do you prefer a leading or trailing return type? Should I also specify the type of the arguments if it is relevant?

Electrux · 2020-04-11T18:46:27Z

Ooh! It looks fantastic! Far better than what I'd have come up with, that's for sure! 😱
The format (including return type) looks just perfect as is!
Yes, I think it would be appropriate to specify argument type(s) where relevant. The reason being that for a lot of functions (see in os module, for example), the arguments are not really obvious and one would have to dig into the source if they want to use a function of that nature.

Also, I wonder if there is some tool (besides doxygen) that could parse and auto generate markdown from c++ source files. In that case, we could simply make and update the function reference while working on it to avoid a lot of manual work. Do you know of any software of that sorts? If not, perhaps we could employ doxygen, or if worthful, create a translator (from C++ comments to markdown) in Feral itself 🤔.
Also, in such case, having a separate API reference would be quite valuable.

What are your thoughts on this?

BenjaminNavarro · 2020-04-12T07:03:31Z

Glad that you like it 😃

I'll add the types, no problem.

I first thought about autogenerating the doc from source code comments but I don't know of a tool which can generate markdown files (Doxygen output is HTML and LaTeX only I think). Moreover, it is easier for people to contribute to the documentation if the only thing they have to do is fork the Book repo, make some changes (can be done from GitHub directly) and create a PR. And they don't have to mess with the source code, which is probably a good point. This is more or less what they do for the Godot game engine, with the docs being on a separate repo and generated (sphinx) based on a mix of hand written and autogenerated rst files. The autogenerated ones are based on hand written xml files describing the API doc (this part is quite ugly tbh)
The only concern with this approach is that it's easier to forget to document an addition to the standard library (although this can be enforced when a PR is submitted) but on the other side, you can make a function documentation as long as you want with multiple code examples without hurting code readability. But maybe there should still be a minimal doxygen doc on the C++ side for the developers.

I don't known, I don't have a perfect answer for all of this, lot of possibilities...

Electrux · 2020-04-12T07:15:38Z

Oh yes! That seems to be the best option. Have a proper document in the book and a (much) smaller autogenerated API reference in the source code.
The autogenerated could be done by doxygen or something and would not interact with the Book whatsoever.
Your point is absolutely valid and quite important that modifications in the book can simply be done by forking the repo.
Thanks for the input 😁.

BenjaminNavarro · 2020-04-12T08:06:17Z

You're welcome!

I just pushed updates for the IO module.

Electrux · 2020-04-12T08:22:25Z

Ooh! Looks really nice! Amazing work!!
Thanks a lot 😁

BenjaminNavarro · 2020-04-12T12:06:31Z

Just quick question, what are the native type names? Here I can see that each type is defined with and without a trailing _t but I don't know which one should be presented to the user.

Electrux · 2020-04-12T12:25:05Z

okay, so... set_typename is what a user sees when they call the .str() member function on an object of class. The Feral VM tries to find the name (if it exists) from type ID, if no name exists, the .str() function will show as typeid<x> where x is the typeid of the type.
The _t variants, on the other hand, are the names of special variables that are created when a type is registered here for example. These variables represent the types themselves, and are used to (usually) bind functions to those types (ie. member functions).
Hope that makes sense 🤔

BenjaminNavarro · 2020-04-12T14:24:27Z

It does, thanks. So I should use the _t variant to document the types in the API?

Electrux · 2020-04-12T14:34:19Z

no, since _t variants are actually variables themselves and not names of types, that would be technically incorrect 🤔
Just the names would be perfectly fine 😁

Electrux · 2020-04-13T04:26:49Z

Great updates! A couple things though:

The Structs and Enums chapter should actually be Lang since that's the name of the module (std.lang).
In strings chapter:
1. The sentence There is no character type in Feral and so are represented are one character strings. seems grammatically incorrect (I think it should be There is no character type in Feral and so are represented as one character strings.)
2. In function signatures, the function names are sometimes prepended with string. and sometimes they are not (push() vs pop()). I think it would be best to just prepend it for every member function name.

Again incredible work! Thanks a bunch! ❤️

BenjaminNavarro · 2020-04-13T06:31:08Z

Ok I will change the chapter name.
1. Yep that's a typo right here, will fix.
2. Yes I missed that ones, thanks for catching that. I initially didn't put anything before the function name but then I got to i_to_c() which is defined on int so I figured it would be better to prepend the type to the function names

Electrux · 2020-04-14T08:45:16Z

wow! cool work on the std.lang module 😱
The examples are really awesome!!!!

By the way, how has been your experience understanding the language till now?
What are the things that can be improved? If there is a lot, please do certainly create an issue about it.

Thanks for the fantastic work 😁

BenjaminNavarro · 2020-04-14T09:40:07Z

You're welcome! I find examples usually more important than the text surrounding them and often what people will look at first, so I focus on that a bit more than the rest.

For now, with my (I hope) good C++ knowledge I can follow quite easily what's going on in the std but for things really language related, I often have to test things to see what works and what doesn't because the docs are still missing 😄

EDIT: I just looked at map.new() and I find it strange to pass all the key/value pairs like key1, value1, key2, value2 instead of key1 = value1, key2 = value2 just like with structs

Electrux · 2020-04-14T10:48:59Z

That's cool 😁. Glad to know that the C++ codebase is at least legible 😂.

About the map.new(), the reason I didn't go with key1 = value, ... format is because that is the syntax of keyword arguments which requires that LHS (key1) be parsed as is instead of being an identifier or expression.
That said, I also think that it could be improved in some way, perhaps something like key1: value1, granted, that will require some additional work on parser as well as bytecode generation stages 🤔.

If you have suggestions regarding that, please do let me know.

BenjaminNavarro · 2020-04-14T12:23:17Z

Ok I see. Another option, although a bit verbose, would be to use arrays to group key/value pairs. eg. map.new([key1, value1], [key2, value2], ...). That should be doable right now because array are heterogeneous so you don't loose the key type information but I don't know if it's a good solution or not.

Electrux · 2020-04-22T17:00:51Z

src/std/2-std-lang.md

+
+The **lang** module offers a way to create user-defined structures and enumerations.
+
+A structure can pack together variables and functions, which allow object-oriented programming.


Electrux · 2020-04-22T17:01:42Z

src/std/2-std-lang.md

+```
+lang.struct(field = value, ...) -> type
+```
+Creates a new structure type type holding a set of `field`s. The given `value`s are used to infer the type of each field and as default values during construction. The return type can be used to instantiate objects of this type.


Electrux · 2020-04-22T17:02:08Z

src/std/2-std-lang.md

+```
+Creates a new structure type type holding a set of `field`s. The given `value`s are used to infer the type of each field and as default values during construction. The return type can be used to instantiate objects of this type.
+
+Adding member functions to a type is done with the `let func in type = fn(args) {}` construct, with `func` being the function's name. Inside the function, variables and functions belonging to the type can be accessed using the `self` keyword.


semicolon after {}

Electrux · 2020-04-22T17:03:34Z

src/std/3-std-strings.md

+The **str** module defines member functions for the native `string` type and other string manipulation related functions.
+The functions available natively in the language can be consulted [here](/13-core-functions.html#string).
+
+A `string` is a sequence of characters. There is no character type in **Feral** and so are represented are one character strings.


so are represented as

Electrux · 2020-04-22T17:07:53Z

src/std/4-std-vectors.md

+```
+vector.slice(start: int, end: int = -1) -> vector
+```
+Extracts the elements from `start` to `end - 1` and returns them in a new vector. If `end == -1` then the slice ends at the end of the vector


you may wanna add:
any modification in the elements of a slice will affect its original vector as well

Electrux · 2020-04-22T17:09:23Z

src/std/5-std-maps.md

@@ -0,0 +1,177 @@
+# Maps
+
+The **map** module defines the `map` type and all the vector manipulation related functions.


~~vector~~ map

Electrux · 2020-04-22T17:11:23Z

src/std/5-std-maps.md

+{Answer?: 42, 0: Zero, 1: One}
+```
+
+Note that the elements are not stored in the order they are given. They are lexicographically sorted


They are not sorted at all - c++'s unordered_map.
From cppreference's unordered_map page:

Internally, the elements are not sorted in any particular order, but organized into buckets. Which bucket an element is placed into depends entirely on the hash of its key. This allows fast access to individual elements, since once the hash is computed, it refers to the exact bucket the element is placed into.

Oops, I was probably thinking of std::map when I wrote this

Electrux · 2020-04-22T17:12:59Z

Just read it. Added some comments.
Awesomely written, as always 😁

BenjaminNavarro · 2020-04-24T09:08:07Z

Thanks for the comments, I'll address them

Electrux · 2020-04-25T09:07:27Z

src/13-core-functions.md

@@ -122,6 +122,6 @@ io.println(hello[5]);

 Output:
 ```
-h
+!
 (nil)


umm... (nil) should have been ! and h should be as it is 😛

Electrux · 2020-04-25T09:11:03Z

src/std/5-std-maps.md

@@ -40,7 +40,7 @@ Gives the output:
 {Answer?: 42, 0: Zero, 1: One}
 ```

-Note that the elements are not stored in the order they are given. They are lexicographically sorted
+Note that the elements are not stored in any particular order and thus does not necessarily follow the given one


~~thus does not~~ thus do not

Electrux · 2020-04-25T09:13:06Z

src/std/10-std-builder.md

@@ -1 +1,175 @@
 # Builder
+
+The **builder** module defines a `builder` type that allows to build and install C++ modules to be used with Feral


builder_t type

~~install C++ modules~~ install external modules
(because it's not C++ exclusive, it can install Feral only modules too)

Electrux · 2020-04-25T09:14:51Z

src/std/10-std-builder.md

+
+The **builder** module defines a `builder` type that allows to build and install C++ modules to be used with Feral
+
+A guide on how to write and build modules for Feral can be read [here](https://levelup.gitconnected.com/writing-c-modules-for-feral-391c30ac7739).


please use this URL:
https://medium.com/p/writing-c-modules-for-feral-391c30ac7739?source=email-852839018f8a--writer.postDistributed&sk=b2de39e5f849e75e3b4ea9bdeeb1b4db

it does not require medium membership

Electrux · 2020-04-25T09:15:41Z

src/std/10-std-builder.md

+
+### new
+```
+builder.new() -> builder


~~-> builder~~ -> builder_t

Electrux · 2020-04-25T09:19:29Z

src/std/10-std-builder.md

+
+Possible output:
+```
+typeid<14>{linker_flags:  , lib_flags:  -lferalvm -lgmpxx -lgmp -lmpfr , lib_dirs:  -L/usr/lib -L/usr/local/lib/feral , srcs:  , ccache: /usr/bin/ccache , compiler: g++, is_dll: false, compiler_opts:  -std=c++11 -O2 , inc_dirs:  -I/usr/include }


in commit 50217df of Feral-Std, added typename for builder_t so now it will show builder_t instead of typeid<14>

Electrux · 2020-04-25T09:20:04Z

src/std/10-std-builder.md

+
+### make_dll
+```
+builder.make_dll() -> builder


~~-> builder~~ -> builder_t

Electrux · 2020-04-25T09:21:12Z

src/std/10-std-builder.md

+
+### add_comp_opts
+```
+builder.add_comp_opts(opt: string) -> builder


~~-> builder~~ -> builder_t

Electrux · 2020-04-25T09:21:19Z

src/std/10-std-builder.md

+
+### add_inc
+```
+builder.add_inc(inc_dir: string) -> builder


~~-> builder~~ -> builder_t

Electrux · 2020-04-25T09:21:42Z

src/std/10-std-builder.md

+
+### add_lib
+```
+builder.add_lib(lib_flag : string, lib_dir = '' : string) -> builder


~~-> builder~~ -> builder_t

Electrux · 2020-04-25T09:21:54Z

src/std/10-std-builder.md

+
+### add_src
+```
+builder.add_src(src: string) -> builder


~~-> builder~~ -> builder_t

Electrux · 2020-04-25T09:22:57Z

src/std/10-std-builder.md

+
+### perform
+```
+builder.perform(output_file: string, .kw_args) -> builder


returns integer, not builder_t
(0 = success, fail otherwise)

Electrux · 2020-04-25T12:03:58Z

src/std/10-std-builder.md

@@ -24,7 +24,7 @@ let sys = import('std/sys');

 ### new
 ```
-builder.new() -> builder
+builder.new() -> builder_t_t


_t_t 😂

🤦‍♂️ Damn, seems I didn't turn on the 'whole word' option when doing the search and replace...

Electrux · 2020-04-26T07:43:38Z

So awesome work!! Thanks a lot! ❤️

Electrux · 2020-04-26T07:47:44Z

okay merged and built. It's available now 😁
https://feral-lang.github.io/Book

Standard library empty pages

f5f9757

BenjaminNavarro mentioned this pull request Apr 11, 2020

Work on Book/Documentation Feral-Lang/Feral#8

Open

23 tasks

Electrux reviewed Apr 11, 2020

View reviewed changes

src/12-standard-library.md Outdated Show resolved Hide resolved

std/io doc update

a278feb

BenjaminNavarro force-pushed the master branch from 1f35387 to a278feb Compare April 12, 2020 08:01

BenjaminNavarro added 3 commits April 12, 2020 20:53

Minors fixes to std/io

13a3a0b

str module documentation

2731052

Fixes in std/str

2f71cce

BenjaminNavarro added 4 commits April 13, 2020 08:31

Fixes in std/str

cf60f71

std/vec doc

5c7aa1c

Minor fixes

885b202

std/lang doc

46db3bf

Electrux reviewed Apr 22, 2020

View reviewed changes

BenjaminNavarro added 2 commits April 24, 2020 11:18

Addressing PR comments

76ee8a4

std/builder doc

4b2bbef