Lisp-like documentation strings

[jandoerntlein]

Lisp docstrings for functions are not ignored by CMera and will be output to the target C/C++ file.

[kiselgra]

I think this one would be pretty cool and we should be able to do it quite safely on the node-level. The idea would be to allow doc-strings as the first element of any body-form encountered. Examples:

(function foo () -> void
   "docstring"
   ...)

(class bar ()
  "docstring"
  (public
    "docstring2"
    (decl ((int i))
      "docstring3"
      ...)))

@lispbub this should be easy, am I right?

[lispbub]

@kiselgra You simply want an optional 'docstring-slot' for statement-nodes?

[kiselgra]

Hm, I'm not sure. I think it would be nicer to have it more fine-grained. I would like, e.g., to have

(class foo ()
  "high-level description"
  ...)

generate

// high level description
class foo {
    ...
};

But for declarations the same behaviour would be strange and I would expect that

(decl ((int i)
      ...)
  "comment"
  ...)

int i;
...
// comment
....

But I think your suggestion would be a good start anyways. We can then still have a look at where we would like to change it and how much of an improvement that would be. We'd need something along those lines anyway. Maybe the slot could go a little higher-up and only be used for list-nodes at the moment. We could then still decide to add different implementations to other nodes.

@lispbub Does that make sense to you?

[lispbub]

Now i get it. You want such doc-strings to be converted to comments in C. The only benefit I see is the more lisp-like notation, but is there another good reason for such a notation (compared to the following:)

(comment "high-level description")
(class foo ()
   ....=

@kiselgra Am I missing something here?

[kiselgra]

The more familiar (and simpler) notation is definitely a positive, but I also would like to have this transparent to macro-processing. Let's say I have an environment-macro that removes certain parts of its body, then this might leave spurious comments around that make no sense in the generated output.

Lets say I have a macro that generates C++ source and header files: (with-interface ...) and write

(with-interface
  (class foo ()
    "documentation that i think should go in the header file"))

This could easily be managed as the class will be kept for the header, but dropped (in some way or another) in the source file. If I have this

(with-interface
  (comment "documentation ....")
  (class ...))

Then there is no properly defined solution to what to do with the comment. The system can only guess where to put it from its surrounding forms, which is something we usually try to avoide due to the complications entailed by it ;)

But I'm still not absolutely sure if the internal wrappers of macros such as with-interface will break under doc-strings. Right now I think this should not be a problem but such things are never that simple :)

Do you see the benefit of this notation?

[lispbub]

You've got a point there. I will add such a functionality :)

[kiselgra]

Cool! Let's do it the easy way first, then see how it works out, if it breaks my current setup :)

[kiselgra]

I think there has been no work on this until now, but I wanted to note that docstrings for the sake of having documentation in the lisp file really do work:

(function foo () -> void
  "docstring"
  (return))

(class bar ()
  "docstring"
  (public
    "docstring2"
    (decl ((int i))
      "docstring3")))

generates

void foo()
{
        return;
}

class bar
{
public:
        int i;
};

But yes, let's finally have a docstring slot for things with a &body.