docify icon indicating copy to clipboard operation
docify copied to clipboard

Can we avoid needing `#[docify::export]`?

Open jsdw opened this issue 1 year ago • 2 comments

#[docify::export] has some nice elements, like allowing us to give nice aliases for eg impl blocks (which otherwise might be hard to "name"), but it also requires that the docify crate be added as a dependency of any crates we'd like to document (I think; I couldn't see a way to make it a dev-dependency and still have doc generation work, and separately I wonder whether you have any thoughts on the best way to do this?).

Anyway, perhaps we can avoid the macro by parsing the rust source ourselves when importing code to document, finding the items named, and taking the relevant item? This would avoid the dependency entirely (and I expect there could be some clever syntax added for eg targeting impl blocks or whatever :))

jsdw avatar Oct 27 '23 09:10 jsdw

Yes I have very much wanted to implement this for some time and this is one of my next targets. Thank you for putting it into an issue because I apparently hadn't made one yet for this

Another thing that could go along with this is proper parsing of paths instead of all items colliding in a global namespace at the file level

sam0x17 avatar Oct 27 '23 21:10 sam0x17

Side note on the dev dependency thing, that actually will suddenly work if we opt for the new syntax suggested in #4. Main reason it doesn't/can't right now is it is illegal to use cfg gates in #[doc = X] position, but "outer attributes" aren't subject to this constraint at all. If I go that route I will just add it as an additional syntax and continue to support the old syntax

sam0x17 avatar Oct 27 '23 21:10 sam0x17