APIView for Rust

[HarshaNalluru]

Issue Azure/azure-sdk-for-rust#1621

Rust API Parser

This repository contains the tool for parsing rustdoc output into API view.

Links

• Branch(Readme): azure-sdk-tools/tools/apiview/parsers/rust-api-parser at harshan/rust-api-parser · HarshaNalluru/azure-sdk-tools
• Input Example: azure-sdk-tools/tools/apiview/parsers/rust-api-parser/clean-rust-doc-output/inputs/docs/src at harshan/rust-api-parser · HarshaNalluru/azure-sdk-tools
• Old Output: azure-sdk-tools/tools/apiview/parsers/rust-api-parser/get-api-view/outputs/docs.rs at harshan/rust-api-parser · HarshaNalluru/azure-sdk-tools
• Current Output:
  

Related work

Output from generate_api_report at Azure/azure-sdk-for-rust#2019 is fed into rust-api-parser here as input.

rust-api-parser

• This TypeScript tool processes the cleaned JSON output from generate_api_report.
• Generates a structured document representing the API view as text.
• Generates a JSON document following the APIView JSON schema that lets us supply the file to the apiview tool directly.
• Organizes the API elements into modules, functions, and other Rust constructs.

Usage

1. Ensure you have Node.js installed. If not, you can install it from nodejs.org.
2. Navigate to the get-api-view folder.
3. Install the necessary dependencies by running:

   npm install
   npm install -g ts-node typescript

4. Run the tool using:

   ts-node main.ts

To Dos

• Transform the current output to the JSON schema expected by the API view tool
• Expand the coverage to span all kinds of elements from the exported API surface
• Finalize the workflow
• Hook up with the APIView Web workflow

[heaths]

It removes private items

Interesting. Last I looked only the public API surface i.e., anything reachable via public API, was included. How did you ascertain elements were truly private?

cargo build

You don't need to do this separately. Just have them run cargo run. Like dotnet run et. al., it'll restore, build, and run. IIRC, only node (npm or similar) makes you do it separately.

[HarshaNalluru]

Last I looked only the public API surface i.e., anything reachable via public API, was included. How did you ascertain elements were truly private?

It's a miss on my part. By filtering with the visibility, I got a much smaller copy of the API that resembled my expected output. I shouldn't have called the others' private.

[LarryOsterman]

It removes private items

Interesting. Last I looked only the public API surface i.e., anything reachable via public API, was included. How did you ascertain elements were truly private?

Does this imply that Rust allows you to access the transitive closure of all types reachable via public API? That is a surprising behavior - most languages hide non-public elements of public APIs (and types referenced by public APIs). Some return errors if a non-public type is returned by a public API (I thought Rust did this), which means that private types reachable via public API were not a thing.

And wouldn't it be the job of rustdoc to figure out which types are public and which types are not public (in other words, the ApiView tool wouldn't necessarily have to handle this).

[HarshaNalluru]

Regarding the private items..

You're right @LarryOsterman. It's a miss on my part in the initial stages. Ignore the comment.
By filtering with the visibility, I got a much smaller copy of the API that resembled my expected output in the initial stages. I shouldn't have called the others' private.
I took my words back and the current version of the parser doesn't take those statements into account.