Further improve ``bindings.rs`` documentation

[Techie-Pi]

This adds a "bin-dependency" to ctru-sys to doxygen-rs, a project I've been working on to improve Doxygen to Rustdoc conversion with ctru-rs in mind: Techie-Pi/doxygen-rs .

Now, every single Doxygen tag used by the bindings is translated (except a few markdown-like tags like p).

Example of the new documentation (also check https://github.com/rust3ds/ctru-rs/pull/75#issuecomment-1276765784):

Maybe adding a dev-dependency is not desired, in that case I could send PRs only with the improvements to bindings.rs, though it would not be easy to automate or to replicate on other machines.

Related: #32 #64 https://github.com/rust-lang/rust-bindgen/issues/955

[Techie-Pi]

CI fails because the changes done in #74 have not been back-ported here

[Techie-Pi]

This last commit adds support for the tags that remained untranslated. Further examples of tags that are now translated

Return values

Clickable references

Clickable links

[Techie-Pi]

(https://github.com/rust3ds/ctru-rs/pull/75#issuecomment-1272537447)

[ian-h-chamberlain]

(Github won't let me comment directly on the file, it seems)

As a minor nit, the spacing for some of the #[doc] attributes seems a bit odd:

#[doc = "Undefined syscall."]
#[doc = ""]

pub const EXCEVENT_UNDEFINED_SYSCALL: ExceptionEventType = 8;
#[doc = "Reasons for an exception event."]
#[doc = ""]

pub type ExceptionEventType = ::libc::c_uint;

I would expect more like

#[doc = "Undefined syscall."]
#[doc = ""]
pub const EXCEVENT_UNDEFINED_SYSCALL: ExceptionEventType = 8;
// maybe no newline here, idk
#[doc = "Reasons for an exception event."]
#[doc = ""]
pub type ExceptionEventType = ::libc::c_uint;

I don't imagine people will read bindings.rs directly very often, so probably not a big deal in general.

[Techie-Pi]

Looks good! I am trying to fix my local toolchain installation to build the docs locally and check them out but your screenshots look like a nice improvement over what was there.

Try deleting the Cargo.lock file on root, that did it for me

[ian-h-chamberlain]

Try deleting the Cargo.lock file on root, that did it for me

Thanks, it was more of an OS-level issue but I got it solved and the docs look good!

Actually on a semi-related note... I wonder if we ought to check in a Cargo.lock for the sake of CI, and maybe add another CI job to the matrix that deletes Cargo.lock before running just to find breakage from upstream. Just a thought

I do see some weird rendering for docstrings on constants, but I'm guessing that's a rustdoc bug and nothing to do with your changes:

example screenshot


Clicking into them seems to work fine so idk what's up with that.

[Techie-Pi]

I do see some weird rendering for docstrings on constants, but I'm guessing that's a rustdoc bug and nothing to do with your changes:

Yeah, that's an issue with Rustdoc, it also happened before #64

[Techie-Pi]

Wait a second, I think I need to check one thing

[Techie-Pi]

Alright, done. I thought I had committed something I shouldn't, but that isn't the case