Rustdoc: unexpected output formatting

[clunion]

Hi All, i am quite new to Rust, and have some questions regarding the output of rustdoc.
My intention is to provide every *.rs file with a header, which is well readable in the code and lets rustdoc generate a nice document from it.
With the following header:

//! ---------------------------------------------------------------------------------------------------------------------------    
//! **`PROJECT:    `** Shardoverse    
//! **`HOME:       `** [Shardoverse on GitHub](https://github.com/clunion/shardoverse)    
//! **`SYNOPSIS:   `** A Roguelike Peer-to-Peer Multi Player Dungeon Explorer Game written in Rust    
//! ---------------------------------------------------------------------------------------------------------------------------    
//! **`FILE:       `** main.rs 🦀   
//! **`DESCRIPTION:`**    
//! The one and only start and entry point of the program.   
//! ---------------------------------------------------------------------------------------------------------------------------    
//! **LICENSE:**   
//! Copyright 2020 by Christian Lunau (clunion), Julian Lunau (someone-out-there) and Jaron Lunau (endless-means).   
//! MIT-License, see LICENSE.md file    
//! ---------------------------------------------------------------------------------------------------------------------------
//! |VERSION:| DATE:      | AUTHOR:   | CHANGES:   
//! |:---    | :---       | :---:     | :---   
//! |0.1     | 2020-04-04 | CLu       | creation   
//! |1.1     | 2020-06-## | CLu       | changed comment style to markdown for rustdoc   
//! ---------------------------------------------------------------------------------------------------------------------------
//! **`TODO:       `**
//! * everything (nearly)
//! ---------------------------------------------------------------------------------------------------------------------------    

(section #examples omitted)
cargo doc --open
generates:

Here, several things i would not have expected:

• All the blue text are 4(!) clickable links, referring to themselves (does that make sense?)
• The link to the page on GitHub is not a discrete link, instead it became part of the link "PROJECT: ... Written in Rust", which points to itself
• The table in markdown is not formatted as a HTML-Table

My questions are:

• Did i not read the correct documentation (Rust Book ch.14, Rustdoc-Book)?
• If so, then which is the right documentation?
• Is this behavior to be considered faulty?
• Should i file a bug report for rustdoc?

Thanks for help and hints,
Clunion

[cuviper]

Text like this:

----
text
----

is one way to write a header in markdown -- even discourse does it here:

---

text

I guess rustdoc is also giving you an anchor link, so you can easily share a specific section.

[clunion]

Wow, that was fast!
Thank you, I'll look into this, didn't know that header-notation...

[cuviper]

More specifically, I guess the first line is a plain horizontal-rule, then the text and underline are the way to write setext headings.

[clunion]

It was indeed the setext header formatting.
Replacing the dash-lines with underscore-lines fixed that.

The markdown table gets formatted as HTML-table,
when the first column of pipes '|' is removed. (only for module level doc comments, in item level doc comment this leading pipe is allowed) Rustdoc is also picky about having a leading space here.

Th following code gives the expected results:

//! ___________________________________________________________________________________________________________________________    
//! **`PROJECT:    `** Shardoverse    
//! **`HOME:       `** [Shardoverse on GitHub](https://github.com/clunion/shardoverse)    
//! **`SYNOPSIS:   `** A Roguelike Peer-to-Peer Multi Player Dungeon Explorer Game written in Rust    
//! ___________________________________________________________________________________________________________________________    
//! **`FILE:       `** main.rs 🦀   
//! **`DESCRIPTION:`**   
//! The one and only start and entry point of the program.   
//! ___________________________________________________________________________________________________________________________    
//! **`LICENSE:    `**   
//! Copyright 2020 by Christian Lunau (clunion), Julian Lunau (someone-out-there) and Jaron Lunau (endless-means).   
//! MIT-License, see LICENSE.md file    
//! ___________________________________________________________________________________________________________________________    
//! VERSION:| DATE:      | AUTHOR:   | CHANGES:   
//! :---    | :---       | :---:     | :---   
//! 0.1     | 2020-04-04 | CLu       | creation   
//! 1.1     | 2020-06-## | CLu       | changed comment style to markdown for rustdoc   
//! ___________________________________________________________________________________________________________________________    
//!# Examples
//!```
//! shardoverse(.exe)
.... (shortened)

-->

Again, Thanks for the help!