extract documentation from (define ...

extract documentation from (define ...

[Jesse Gibbons]

I am trying to generate documentation for a project written in guile. I
tried "guild doc-snarf" [0] but apparently it only recognizes
documentation in double-semicolon comments. A lot of the project is
documented in a string like one would document an emacs-lisp function.
Is there a program to extract that kind of documentation?

[0]: http://git.savannah.gnu.org/cgit/guile.git/tree/module/scripts/doc
-snarf.scm

Re: extract documentation from (define ...

[sirgazil via General Guile related discussions]

---- On Sun, 01 Sep 2019 16:45:23 -0500 Jesse Gibbons <jgibbons2357@gmail.com> wrote ----

I am trying to generate documentation for a project written in guile. I 
tried "guild doc-snarf" [0] but apparently it only recognizes 
documentation in double-semicolon comments. A lot of the project is 
documented in a string like one would document an emacs-lisp function. 
Is there a program to extract that kind of documentation? 
 
[0]: http://git.savannah.gnu.org/cgit/guile.git/tree/module/scripts/doc 
-snarf.scm 
 





I don't know of any program like that for Guile. I was looking for one myself years ago, but couldn't find anything. However, you can extract procedure documentation strings and other metadata using https://www.gnu.org/software/guile/manual/html_node/Procedure-Properties.html. And if you use texinfo for your documentation, take a look at https://www.gnu.org/software/guile/manual/html_node/Texinfo-Processing.html.

Re: extract documentation from (define ...

[Jan Nieuwenhuizen]

Jesse Gibbons writes:

> I am trying to generate documentation for a project written in guile. I
> tried "guild doc-snarf" [0] but apparently it only recognizes
> documentation in double-semicolon comments. A lot of the project is
> documented in a string like one would document an emacs-lisp function.
> Is there a program to extract that kind of documentation?

For Emacsy[0] I have used a guild doc-snarf but am now switching to doc
strings using.  See the `wip-doc' branch and esp.

    https://git.savannah.nongnu.org/cgit/emacsy.git/tree/scripts/document-module.scm?h=wip-doc

You may want to look at the Makefile.am as well for how it's used.

HTH,
janneke

[0] https://savannah.nongnu.org/projects/emacsy

-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

Re: extract documentation from (define ...

[Vladimir Zhbanov]

On Mon, Sep 02, 2019 at 07:19:15AM +0200, Jan Nieuwenhuizen wrote:
> Jesse Gibbons writes:
> 
> > I am trying to generate documentation for a project written in guile. I
> > tried "guild doc-snarf" [0] but apparently it only recognizes
> > documentation in double-semicolon comments. A lot of the project is
> > documented in a string like one would document an emacs-lisp function.
> > Is there a program to extract that kind of documentation?
> 
> For Emacsy[0] I have used a guild doc-snarf but am now switching to doc
> strings using.  See the `wip-doc' branch and esp.
> 
>     https://git.savannah.nongnu.org/cgit/emacsy.git/tree/scripts/document-module.scm?h=wip-doc
> 
> You may want to look at the Makefile.am as well for how it's used.

Cool, thanks!

The only issue i see is no docstrings found for C code
SCM_DEFINE'd Scheme procedures.  Probably there might be some
work-around, too (could the optional args of the
module-stexi-documentation() procedure change something here?).
Anyway, I'm pretty happy to see such functionality in Guile :-)

-- 
  Vladimir

(λ)επτόν EDA — https://github.com/lepton-eda

Re: extract documentation from (define ...

[Jan Nieuwenhuizen]

Vladimir Zhbanov writes:

>> For Emacsy[0] I have used a guild doc-snarf but am now switching to doc
>> strings using.  See the `wip-doc' branch and esp.
>> 
>>     https://git.savannah.nongnu.org/cgit/emacsy.git/tree/scripts/document-module.scm?h=wip-doc
>> 
>> You may want to look at the Makefile.am as well for how it's used.
>
> Cool, thanks!
>
> The only issue i see is no docstrings found for C code
> SCM_DEFINE'd Scheme procedures.

You'll have to modify SCM_DEFINE, its last argument is the docstring.
For another project, I am doing something like

--8<---------------cut here---------------start------------->8---
#undef SCM_DEFINE
#define SCM_DEFINE(FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)  \
SCM_SNARF_HERE(                                                         \
SCM_UNUSED static const char s_ ## FNAME [] = PRIMNAME;                 \
static SCM FNAME ARGLIST                                                \
)                                                                       \
SCM_SNARF_INIT(                                                         \
scm_c_define_gsubr (s_ ## FNAME, REQ, OPT, VAR,                         \
                    (SCM_FUNC_CAST_ARBITRARY_ARGS) FNAME);              \
scm_c_set_procedure_properties (PRIMNAME, __FILE__, __LINE__,  DOCSTRING);\
)                                                                       \
SCM_SNARF_DOCS(primitive, FNAME, PRIMNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING)

void
scm_c_set_procedure_properties (char const* name, char const* file_name, int line, char const* doc_string)
{
  SCM proc = scm_variable_ref (scm_c_lookup (name));
  scm_set_source_property_x (proc,
                             scm_from_utf8_string ("documentation"),
                             scm_from_utf8_string (doc_string));
  scm_set_source_property_x (proc,
                             scm_from_utf8_symbol ("location"),
                             scm_list_2 (scm_cons (scm_from_utf8_string ("file-name"),
                                                   scm_from_utf8_string (file_name)),
                                         scm_cons (scm_from_utf8_string ("line"),
                                                   scm_from_int (line))));
}
--8<---------------cut here---------------end--------------->8---


The scm_c_set_procedure_properties could be more standard compliant,
hopefully.

HTH,
janneke

-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

Re: extract documentation from (define ...

[Vladimir Zhbanov]

On Mon, Sep 02, 2019 at 07:50:40PM +0200, Jan Nieuwenhuizen wrote:
> Vladimir Zhbanov writes:
> 
> >> For Emacsy[0] I have used a guild doc-snarf but am now switching to doc
> >> strings using.  See the `wip-doc' branch and esp.
> >> 
> >>     https://git.savannah.nongnu.org/cgit/emacsy.git/tree/scripts/document-module.scm?h=wip-doc
> >> 
> >> You may want to look at the Makefile.am as well for how it's used.
> >
> > Cool, thanks!
> >
> > The only issue i see is no docstrings found for C code
> > SCM_DEFINE'd Scheme procedures.
> 
> You'll have to modify SCM_DEFINE, its last argument is the docstring.
> For another project, I am doing something like
> 
> --8<---------------cut here---------------start------------->8---
> #undef SCM_DEFINE
> #define SCM_DEFINE(FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)  \
> SCM_SNARF_HERE(                                                         \
> SCM_UNUSED static const char s_ ## FNAME [] = PRIMNAME;                 \
> static SCM FNAME ARGLIST                                                \
> )                                                                       \
> SCM_SNARF_INIT(                                                         \
> scm_c_define_gsubr (s_ ## FNAME, REQ, OPT, VAR,                         \
>                     (SCM_FUNC_CAST_ARBITRARY_ARGS) FNAME);              \
> scm_c_set_procedure_properties (PRIMNAME, __FILE__, __LINE__,  DOCSTRING);\
> )                                                                       \
> SCM_SNARF_DOCS(primitive, FNAME, PRIMNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING)
> 
> void
> scm_c_set_procedure_properties (char const* name, char const* file_name, int line, char const* doc_string)
> {
>   SCM proc = scm_variable_ref (scm_c_lookup (name));
>   scm_set_source_property_x (proc,
>                              scm_from_utf8_string ("documentation"),
>                              scm_from_utf8_string (doc_string));
>   scm_set_source_property_x (proc,
>                              scm_from_utf8_symbol ("location"),
>                              scm_list_2 (scm_cons (scm_from_utf8_string ("file-name"),
>                                                    scm_from_utf8_string (file_name)),
>                                          scm_cons (scm_from_utf8_string ("line"),
>                                                    scm_from_int (line))));
> }
> --8<---------------cut here---------------end--------------->8---
> 
> 
> The scm_c_set_procedure_properties could be more standard compliant,
> hopefully.

Thanks! Would be nice if the changes go to the guile code and the
`stexi` functions become even more nice :-)

-- 
  Vladimir

(λ)επτόν EDA — https://github.com/lepton-eda

Re: extract documentation from (define ...

[Mark H Weaver]

Hi Jesse,

Jesse Gibbons <jgibbons2357@gmail.com> writes:

> I am trying to generate documentation for a project written in guile. I
> tried "guild doc-snarf" [0] but apparently it only recognizes
> documentation in double-semicolon comments. A lot of the project is
> documented in a string like one would document an emacs-lisp function.
> Is there a program to extract that kind of documentation?
>
> [0]: http://git.savannah.gnu.org/cgit/guile.git/tree/module/scripts/doc
> -snarf.scm

I would use 'object-documentation' procedure from (ice-9 documentation),
which is what underlies the ,describe REPL command.

       Best,
        Mark