[ARROW-11179] [Format] Make comments in fb files friendly to rust doc

• Type: Improvement
• Status: Resolved
• Priority: Trivial
• Resolution: Fixed
• Fix Version/s: 4.0.0
• Component/s: Documentation, Format
• Labels: pull-request-available
• External issue URL: https://github.com/apache/arrow/issues/27084
• Assignee: Qingyou Meng
• Reporter: Qingyou Meng
• Created: 08/Jan/21 06:33
• Updated: 11/Jan/23 08:18
• Resolved: 30/Jan/21 21:36

Description

Currently, comments in flatbuffer files are directly copied to rust and c++ source codes.

That's great but there are some problems with cargo doc:

• array element abc[1] or link label [smith2017knl] causes `broken intra doc links` warning
• example code/figure blocks are flatten into one line, see example arrow 2.0.0 doc

After flatc generating, those ipc files have to be updated manually to fix the above problems.

So I'm suggesting update flatbuffer comments to address this problem.

• Escape inline code with ` and `
• Escape text block with ```text and ```
• change [smith2017knl]: http://shaden.io/pub-files/smith2017knl.pdf to [smith2017knl](http://shaden.io/pub-files/smith2017knl.pdf)

The attachment file format-0ed34c83.patch is created with git command

git diff 0ed34c83 -p format > format-0ed34c83.patch

where 0ed34c83 is this commit: 

0ed34c83c ARROW-9400: [Python] Do not depend on conda-forge static libraries in Windows wheel builds

emkornfield may I create a pull request for this?

Issue Links

• links to: GitHub Pull Request #9299