Document every procedure, variable and file #31

pastor commented 2025年05月30日 18:14:09 +02:00

One of the great thing of Emacs is a de-facto standard to add docstrings to every procedure and variable. This makes it very accessible as an extensible platform.

I believe we ought to do the same before the release, and we should set ourselves the goal of adding a docstring for every procedure, a comment for every variable and a introductory paragraph for each blue module. This will truly make B.L.U.E the Build Language User Extensible we strive to create.

One of the great thing of Emacs is a de-facto standard to add docstrings to every procedure and variable. This makes it very accessible as an extensible platform. I believe we ought to do the same before the release, and we should set ourselves the goal of adding a docstring for every procedure, a comment for every variable and a introductory paragraph for each blue module. This will truly make B.L.U.E the Build Language User Extensible we strive to create.

old commented 2025年05月30日 18:43:23 +02:00

Yes. But not everything is made public in that some modules are not meant to be used by end-users.

I want us to be careful to what we expose, because it then become API and we can not just change it without breaking backward compatibility.

Yes. But not everything is made public in that some modules are not meant to be used by end-users. I want us to be careful to what we expose, because it then become API and we can not just change it without breaking backward compatibility.

pastor commented 2025年05月31日 00:05:26 +02:00

Well documenting things and exposing them as API are separate things. I meant that, before the release, we should have a fully documented code base.

There is no reason for not documenting code and it will encourage future contributors.

Well documenting things and exposing them as API are separate things. I meant that, before the release, we should have a fully documented code base. There is no reason for not documenting code and it will encourage future contributors.

old commented 2025年05月31日 00:34:23 +02:00

Okay I'm fine with this. But I would avoid making the info manual by snarfing comments and stuffs like this if we don't have a way to filter-out what's not API.

Okay I'm fine with this. But I would avoid making the info manual by snarfing comments and stuffs like this if we don't have a way to filter-out what's not API.

pastor commented 2025年06月07日 14:00:08 +02:00

Just to clarify. By document, I also meant to add comments. So if we don't want to add docstrings to internal procedures, that's fine. But we should, at least, add a comment above them.

I would like to to maintain a high standard before we make the beta release. One of the goals that I have for BLUE, is to make it a didactic piece of software that newcomers to Guile can use as a reference, and learn from it.

I know with you experience in Guile, you could find some comments unnecessary, in which case I would recommend you the hide-comnt.el Emacs package.

It's very useful for keep a highly commented code base while maintaining a low line count during development.

Just to clarify. By document, I also meant to add comments. So if we don't want to add docstrings to internal procedures, that's fine. But we should, at least, add a comment above them. I would like to to maintain a high standard before we make the beta release. One of the goals that I have for BLUE, is to make it a didactic piece of software that newcomers to Guile can use as a reference, and learn from it. I know with you experience in Guile, you could find some comments unnecessary, in which case I would recommend you the [hide-comnt.el](https://www.emacswiki.org/emacs/HideOrIgnoreComments) Emacs package. It's very useful for keep a highly commented code base while maintaining a low line count during development.