[
https://issues.apache.org/jira/browse/ARROW-11179?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
meng qingyou updated ARROW-11179:
---------------------------------
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`, for example:
* 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|https://docs.rs/arrow/2.0.0/arrow/ipc/gen/SparseTensor/struct.SparseTensorIndexCSF.html#method.indptrType]
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 {color:#00875a}[smith2017knl]:
{color}{color:#00875a}[http://shaden.io/pub-files/smith2017knl.pdf]{color} to
{color:#403294}[smith2017knl]({color}{color:#403294}[http://shaden.io/pub-files/smith2017knl.pdf]){color}
[~emkornfield] may I create a pull request for this?
was:
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`, for example:
* 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|https://docs.rs/arrow/2.0.0/arrow/ipc/gen/SparseTensor/struct.SparseTensorIndexCSF.html#method.indptrType]
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 {color:#00875a}[smith2017knl]:
{color}[{color:#00875a}[http://shaden.io/pub-files/smith2017knl.pdf]{color}] to
{color:#403294}[smith2017knl]({color}{color:#403294}[http://shaden.io/pub-files/smith2017knl.pdf]){color}
[~emkornfield] may I create a pull request for this?
> [Format] Make comments in fb files friendly to rust doc
> -------------------------------------------------------
>
> Key: ARROW-11179
> URL: https://issues.apache.org/jira/browse/ARROW-11179
> Project: Apache Arrow
> Issue Type: Improvement
> Reporter: meng qingyou
> Priority: Major
>
> 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`, for example:
> * 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|https://docs.rs/arrow/2.0.0/arrow/ipc/gen/SparseTensor/struct.SparseTensorIndexCSF.html#method.indptrType]
> 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 {color:#00875a}[smith2017knl]:
> {color}{color:#00875a}[http://shaden.io/pub-files/smith2017knl.pdf]{color} to
> {color:#403294}[smith2017knl]({color}{color:#403294}[http://shaden.io/pub-files/smith2017knl.pdf]){color}
> [~emkornfield] may I create a pull request for this?
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
