Add some overview to the RRGraphView doxygen documentation

[treelin611]

Description

• Add high level comments on RRGraphView class
• Reformat comment to be doxygen-compatible

Related Issue

• This Pull request is related to an existing issue Add Doxygen-style comments to RRGraphView and RRGraphBuilder, and make new VPR API tab #1834

[vaughnbetz]

Looks very good, thanks!

[vaughnbetz]

I think you'll have to explain what this means a bit more, or shorten/delete it. Is this saying that as the RRGraphView allows all the RRGraph data to be viewed, it can be used by multiple clients, which saves memory?

[treelin611]

I just rewrote the overview section according to "possible solution" in this link: #2361.

[vaughnbetz]

That looks great ... thanks!

[treelin611]

No problem! A small bug has also been fixed. The PR should be ready now.

[tangxifan]

@treelin611 You may refer to the following text when adding the fundamental description
@vaughnbetz Please advise if the following description is accurate enough

vtr-verilog-to-routing/libs/librrgraph/src/base/rr_graph_obj.h

Lines 14 to 47 in b9760a9

	* A Routing Resource Graph (RRGraph or RRG) is a directed graph (has many cycles),
	* which consists of a number of nodes and edges.
	*
	* Node
	* ----
	* Each node represents a routing resource, which could be
	* 1. a routing track in X-direction or Y-direction (CHANX or CHANY)
	* 2. an input or an output of a logic block (IPIN or OPIN)
	* 3. a virtual source or sink node (SOURCE or SINK), which are starting/ending points of routing trees.
	*
	* Edge
	* ----
	* Each edge represents a switch between routing resources, which could be
	* 1. a multiplexer
	* 2. a tri-state buffer
	* 3. a pass gate
	* 4. a non-configurable (can not be turned off) buffer
	* 5. a short (metal connection that can not be turned off
	*
	* Note: Multiplexers are the most common type
	*
	* The switch information are categorized in the rr_switch_inf of RRGraph class.
	* rr_switch_inf is created to minimize memory footprint of RRGraph classs
	* While the RRG could contain millions (even much larger) of edges, there are only
	* a limited number of types of switches.
	* Hence, we use a flyweight pattern to store switch-related information that differs
	* only for types of switches (switch type, drive strength, R, C, etc.).
	* Each edge stores the ids of the switch that implements it so this additional information
	* can be easily looked up.
	*
	* Note: All the switch-related information, such as R, C, should be placed in rr_switch_inf
	* but NOT directly in the edge-related data of RRGraph.
	* If you wish to create a new data structure to represent switches between routing resources,
	* please follow the flyweight pattern by linking your switch ids to edges only!

[vaughnbetz]

Lots of good information there n good hat link ... I suggest adding a pointer and/or directly moving some over.

[treelin611]

Thanks for the link. It is very informative. I have added some information from it into the current RRGraphView. The final documentation will be as follows:

[vaughnbetz]

Looks great, thanks. Will build once the basic CI passes (the google runners are down, so the bigger _nightly tests won't run but they aren't needed for this change).