andrewdavidmackenzie
Allow function implementations to include definition into code docs
See this, and implement when on stable: https://doc.rust-lang.org/unstable-book/language-features/external-doc.html
#[doc(include = "compare_switch.toml")] #[derive(Debug)] pub struct CompareSwitch;
so that the toml definition file is included into the doc comments of the code and is then in the generated docs.
<------ Target 'code-docs' starting
warning: unresolved link to input
--> flowstdlib/control/compare_switch/compare_switch.rs:6:1
|
6 | / /// Compare two input values and output different the right hand value at different output route
7 | | /// corresponding to is equal, greater than, greater than or equal, less than or less than or equal.
8 | | ///
9 | | /// ## Include using
... |
15 | |
16 | | #[doc(include = "compare_switch.toml")]
| |_______________________________________^
|
= note: #[warn(broken_intra_doc_links)] on by default
= note: the link appears in this line:
[[input]]
^^^^^
= help: to escape [ and ] characters, add '' before them like \[ or \]
warning: unresolved link to input
--> flowstdlib/control/compare_switch/compare_switch.rs:6:1
|
6 | / /// Compare two input values and output different the right hand value at different output route
7 | | /// corresponding to is equal, greater than, greater than or equal, less than or less than or equal.
8 | | ///
9 | | /// ## Include using
... |
15 | |
16 | | #[doc(include = "compare_switch.toml")]
| |_______________________________________^
|
= note: the link appears in this line:
[[input]]
^^^^^
= help: to escape [ and ] characters, add '' before them like \[ or \]
warning: unresolved link to output
--> flowstdlib/control/compare_switch/compare_switch.rs:6:1
|
6 | / /// Compare two input values and output different the right hand value at different output route
7 | | /// corresponding to is equal, greater than, greater than or equal, less than or less than or equal.
8 | | ///
9 | | /// ## Include using
... |
15 | |
16 | | #[doc(include = "compare_switch.toml")]
| |_______________________________________^
|
= note: the link appears in this line:
[[output]]
^^^^^^
= help: to escape [ and ] characters, add '' before them like \[ or \]
warning: 3 warnings emitted
Works, but you loose all formatting:
function = "CompareSwitch" implementation = "compare_switch.rs"
[[input]] name = "left" type = "Number"
[[input]] name = "right" type = "Number"
[[output]] name = "equal" type = "Number"
[[output]] name = "right-lt" type = "Number"
[[output]] name = "right-lte" type = "Number"
[[output]] name = "right-gt" type = "Number"
[[output]] name = "right-gte" type = "Number"
[[output]] name = "left-lt" type = "Number"
[[output]] name = "left-lte" type = "Number"
[[output]] name = "left-gt" type = "Number"
[[output]] name = "left-gte" type = "Number"
I think the best might be to try and generate the spec from the doc comments? so code and spec is together, and that opens the door for macros to help write the code and generate the doc commennts.