News for hackers. Stuff that matters.
Re:Block Comments Are a Bad Idea by chrismorgan on Wednesday October 11, 2017 @09:37AM (#15449600)
Rust supports block comments and line comments; the recommended style is “don’t use block comments”. I have never felt any inclination to use block comments in Rust. These examples of doc comments (using slash-star-star or triple slash instead of slash-star or double slash which are plain comments) are all equivalent, and I know which one I find to be nicest (the third, with line comments):

  /**
   * This is documentation.
   *
   * It spans multiple paragraphs.
   */
  pub fn foo() {}

  /**
  This is documentation.
  
  It spans multiple paragraphs.
  */
  pub fn foo() {}

  /// This is documentation.
  ///
  /// It spans multiple paragraphs.
  pub fn foo() {}

  #[doc = "This is documentation."]
  #[doc = ""]
  #[doc = "It spans multiple paragraphs."]
  pub fn foo() {}
(You can mix-and-match, too; I’ve combined doc attributes with cfg_attr before, to add doc comments if a certain feature is enabled, see the bonus section in https://chrismorgan.info/blog/rust-cfg_attr.html.)

There are no comments on this comment yet.