[ 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 to `cargo doc`, for example: * array element abc[1] or link label [smith2017knl] causes `broken intra doc links` warning * figures/code blocks are flatten into one line [example from arrow 2.0.0doc|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 to `cargo doc`, for example: * array element abc[1] or link label [smith2017knl] causes `broken intra doc links` warning * figures/code blocks are flatten into one line [example from arrow 2.0.0doc|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 to `cargo doc`, for example: > * array element abc[1] or link label [smith2017knl] causes `broken intra doc > links` warning > * figures/code blocks are flatten into one line [example from arrow > 2.0.0doc|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)