Function prototypes or documentation

[Jamesinvi]

Hi everyone.
First of all, love the language, it feels like what I would like C to be with some extra bits which turn out to be really useful. Great job!

I'm using C3 for a toy language implementation, for both the parser/code-gen and the VM.

My question is about function prototypes (pre-declaration) and/or documentation.
I find that the best C libraries usually have header files which contains all function prototypes and a very good explanation on what it does and what the params are, but the implementation is somewhere else and is not important to know how it works.
Is there a way to achieve something similar in C3 in any way (same file or different file, doesn't really matter)?

Because right now my "documentation" comments get drowned by all the noise of the function implementations. I noticed there's a future feature "c3c docs", is that potentially what I'm looking for?

Thanks for the help!

[Book-reader]

The docs/ folder in a project is there for a potential future docs generator that uses doc comments or for writing your own docs manually, there isn't anything automatic yet.
C3 does have .c3i interface files as a parallel to C .h files which can be used to put dedicated documentation comments, however they have a few more limitations than in C: they are only intended to be used to interface with precompiled libraries and not for forward declarations, so if you have a .c3i file that has the same declarations as a .c3 they will cause conflicting defitions when compiled together:

// mylib.c3
module mylib;
import std::io;

fn void some(int x)
{
  io::printfn("Hello, World! %s", x);
}

// mylib.c3i
module mylib;

<*
 My documentation
 param x : "something" // normally this would be <at symbol>param but the github highlighting is a bit broken rn
*>
fn void some(int x);

// somefile.c3
module some;
import mylib;

fn void main()
{
  mylib::some(12345);
}

$ c3c compile-run somefile.c3 mylib.c3 mylib.c3i
ERROR: function `some` from module `mylib` declared twice.

if this is fine with you then you could put your docs in a .c3i file that's separate from the main source files and doesn't get included in normal compilation.

[Book-reader]

I just remembered you could also mark the module declaration in the .c3i file with @if(false) to exclude its contents from compilation:

// mylib.c3
module mylib;
import std::io
fn void some(int x)
{
  io::printfn("Hello, World! %s", x);
}

// mylib.c3i
module mylib @if(false);

<* My documentation *>
fn void some(int x);

// somefile.c3
module some;
import mylib;

fn void main()
{
  mylib::some(12345);
}

$ c3c compile-run somefile.c3 mylib.c3 mylib.c3i
Hello, World! 12345

it's a bit of a hack but it should work

[Jamesinvi]

I see, so I understood correctly that this "feature" is not really intended to exist. I really like the documentation to be in the code itself instead of a web-page or separate files. Having a list of functions with a small explanations in a "header" is just a compact and clean way of having that.

It is a pity but not a deal breaker, I will probably wait for when the auto "docgen" feature gets developed, and will likely use that.

Thank you for taking the time to answer my question :)

[lerno]

Also follow #2923