On 15.07.2013 15:07, Corey Richardson wrote: > On Mon, Jul 15, 2013 at 9:03 AM, Jordi Boggiano <j.boggi...@seld.be> wrote: >> [snip] >> - Full reorganization of the doc blocks with special tags/annotations à >> la javadoc [2], I am not a particular fan of that but for special things >> it does serve it's purpose and has the advantage of being somewhat >> widespread. >> > > For some things, we can attach an attribute to the item. For example, > https://github.com/mozilla/rust/issues/723 would be included in the > documentation somehow, rather than the Javadoc-like solution of > in-comment annotation.
Interesting indeed, and definitely when possible I would favor real annotations to in-comment ones, that way the code won't compile unless the docs format is valid. However as bjz mentioned [1] it would be nice to have more metadata attached to it like an alternative and date/version at which it will disappear. [1] https://github.com/mozilla/rust/issues/723#issuecomment-10351828 Cheers -- Jordi Boggiano @seldaek - http://nelm.io/jordi _______________________________________________ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
