From: "ufuk (Ufuk Kayserilioglu) via ruby-core" <ruby-core@...>
Date: 2024-08-15T10:04:46+00:00
Subject: [ruby-core:118859] [Ruby master Bug#20678] Doxygen document doesn't print Ruby C APIs properly

Issue #20678 has been updated by ufuk (Ufuk Kayserilioglu).


I believe it is being generated. Probably not where you expect it to be, though: https://docs.ruby-lang.org/capi/en/master/d7/d19/group__defmethod.html#gaa7bed88640f01bee619f85fda09d28d7

Btw, since https://bugs.ruby-lang.org/issues/20639, the C API documents generated by Doxygen are being published at https://docs.ruby-lang.org/capi/en/master/

----------------------------------------
Bug #20678: Doxygen document doesn't print Ruby C APIs properly
https://bugs.ruby-lang.org/issues/20678#change-109428

* Author: jaruga (Jun Aruga)
* Status: Open
* Backport: 3.1: UNKNOWN, 3.2: UNKNOWN, 3.3: UNKNOWN
----------------------------------------
I am looking for how to see a list of Ruby C API descriptions written in the comment area by a command.

For example, in the case of the `rb_scan_args`, the description is below.
https://github.com/ruby/ruby/blob/908305a2977856264a932cad02437c30f08c365b/include/ruby/internal/scan_args.h#L93-L147

The `ri` command only shows a very simple text rather than the above description.

```
$ ri rb_scan_args
= .rb_scan_args

(from ruby core)
=== Implementation from C
------------------------------------------------------------------------
  rb_scan_args(method_body)

------------------------------------------------------------------------

Extracts parameters from the method_body and returns a method parameter
string.  Follows 1.9.3dev's scan-arg-spec, see README.EXT
```

@nobu gave me a clue to print the list of such descriptions by using `doxygen`.

Below are the steps I tested at the latest ruby/ruby master branch 2a933609e75aa87f27cf1c892a54389d3efed928 on my Fedora Linux 39.

Installed Doxygen.

```
$ sudo dnf install doxygen

$ which doxygen
/bin/doxygen

$ doxygen --version
1.9.7

$ rpm -q doxygen
doxygen-1.9.7-3.fc39.x86_64
```

Generated the Doxygen document. Then the `doc/capi` directory was created.

```
$ ./autogen.sh

$ ./configure ...<snip>...
...
checking for doxygen... doxygen
...

$ make capi
```


Opened the Main page.

```
$ firefox doc/capi/html/index.html &
```

Then I cannot find the document about `rb_scan_args` on the Main Page (`ruby_doxygen_main_page.png`) and Namespace List (`ruby_doxygen_namespace_list.png`) page.

Do you know what's the reason and what's wrong? I don't think all the Ruby APIs are listed on the page. I assume there may be a bug in the process of generating the doxygen document.







---Files--------------------------------
ruby_doxygen_main_page.png (55.8 KB)
ruby_doxygen_namespace_list.png (164 KB)


-- 
https://bugs.ruby-lang.org/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/