Re: Comment style docstrings

[Michael Livshin]

Keisuke Nishida <address@hidden> writes:

> So far docstrings of primitive procedures have been written as
> C strings in C files.  Shouldn't we use a comment style like this?
>
> [ snip the example ]
>
> Rationale:
> 
>  1. Docstrings are unlikely used as real C strings.
>     There is no reason to represent them by C strings.

OK.

>  2. Scheme files are going to use a comment style.

is that a fact?

>     We should use the same style in C files.
> 
>  3. The above style is easier to modify, read, and parse
>     than the current style.

easier to read/parse by whom?

strings have the nice advantage of not needing to be parsed at all.
as for comments, we'd need some tool to extract them.

>  4. Docstrings in this style can be used for non-procedures,
>     including macros, classes, and smob types, without any
>     extension to C code.

good point.  strings too, though.

> The only drawback I can think of is that this style of
> docstrings are always extracted unconditionally regardless
> of #if statements in C files (unless we parse them as well).
> I think this is not a big issue.

probably not a big issue, right.

> If it is okay, I'll write a converter from the current style
> to the above style, a parser for comment style docstrings, and
> Emacs commands that help writing the new style of docstrings
> when I have time.

I personally would love to see you pounding on the VM/compiler, but
who the hell am I to make suggestions. ;)

anyway, you might as well consider writing some sort of C parsing
library for Guile, and snarf out the docs using it.  it could also
find other interesting uses, I'm sure.

is there some nice wrappable C parser out there?  I might well find
half a day to wrap it, it being holidays here.

[ as an aside: I think Guile sees an unjustified amount of
  infrastructure improvements and cleanups lately, which doesn't seem
  too healthy to me.  but it's free software, so I'll just shut up.
  sorry.  thank you. ]

-- 
You cannot really appreciate "Dilbert" unless you've read it in the
original Klingon.
                                        -- Klingon Programmer