chore: added Pallas compatible comments

[tobehn]

I do not know if this is relevant to you.
When i saw Pallas i went through the system to see how it generates the HTML sites.

I realized it needs the comments in order to provide the small description for each function and struct.
Then i started going through Vib and added the descriptions in core everywhere it was missing.

If this is accepted i would go on with adding descriptions.
Let me know if this is wasted time.
Cheers.

[axtloss]

This is actually very helpful, thanks for taking the time to create this

but I find the format of the comments to be a bit weird, the comments shouldn't include the function name, and also should be written in the present tense
as an example for the ChangeWorkingDirectory function:

// Add a WORKDIR instruction to the containerfile

[tobehn]

Great to hear its helpful.

Well, i get your point.
I think i derived the comments from the ABRoot ones.

For example the comment for generateABGrubConf in ABRoot is //generateABGrubConf generates a new grub config with the given details > https://abroot.vanillaos.org/core.html#generateABGrubConf

Perhaps this is generally not the format style you'd prefer.
I think we should agree on a rather generic comment format for all !GO / Pallas documented software

[axtloss]

Yeah I'm not a fan of the current commenting style, but until we have a set standard i'd keep the format i mentioned for vib

[tobehn]

All right I am going to enhance the comments.

[axtloss]

Already good, but one thing is that the return of a function should be seperarated
instead of "builds xyz and returns abc", it should be

builds xyz
returns: abc

[mirkobrombin]

Small note: Pallas does not care about how you define returns and parameters, it will threat both as a description and always parse both from the AST instead.

[axtloss]

Small note: Pallas does not care about how you define returns and parameters, it will threat both as a description and always parse both from the AST instead.

Yeah I know, but it's easier to read from the description that way, since it makes it easier to spot

[tobehn]

Small note: Pallas does not care about how you define returns and parameters, it will threat both as a description and always parse both from the AST instead.

This is what I also thought.
So in case I write the return into the comment it currently would be rendered into the Pallas generated description where you have a separate section for the returns below.

@mirkobrombin would it be possible to exclude everything from the comment starting with string “return:” from the description in Pallas?
Or even better use it as additional information for the Returns: section.

It then could fit the needs for reading in the code and in the dev documentation.

[mirkobrombin]

It is possible, not sure if it is worth it, not sure if we should be opinionated in that side

[tobehn]

It also came to my mind it might be difficult to track whether all returns of the function are recorded correctly in the comment.

I'd prefer to use the current auto generation of the functions returns and do not specifically create a section in the comment (=description). In some comments i could describe the returns though, in case they are important.

[tobehn]

solved by ddd1e3a

[axtloss]

It is possible, not sure if it is worth it, not sure if we should be opinionated in that side

It is, pallas only tells the users the type of the return, not what it returns, which is very important to have

[axtloss]

It also came to my mind it might be difficult to track whether all returns of the function are recorded correctly in the comment.

I don't see how it would be difficult, its not the exact value it returns, but what the return value means, if it's difficult to properly track what the function returns then the function needs to be reworked

[mirkobrombin]

It is possible, not sure if it is worth it, not sure if we should be opinionated in that side

It is, pallas only tells the users the type of the return, not what it returns, which is very important to have

In that case a proper mapping would be better instead of just removing Returns from the comment

Or even better use it as additional information for the Returns: section.

Didn't see this comment

[axtloss]

Some small nitpicks that i came across while going through the changes, starting to look pretty nice though

[axtloss]

@tobehn any update on this? is it ready to merge?

[tobehn]

@tobehn any update on this? is it ready to merge?

From my point of view the comments are done.

[axtloss]

Alright, could you squash your commits into one so that I can merge it?

[tobehn]

oh gosh, it looks to me like i messed it up.
I've never done a squashing before. Can you tell if i have done it right?

[axtloss]

Yep, everything's great and how it's supposed to be.
Thanks for going through the effort and commenting everything!