support for comments (module, net def, io def, statement)

Author: Nic30

include/netlistDB/netlist.h

@@ -60,16 +60,17 @@ class NETLISTDB_PUBLIC SensitivityInfo {
  * @ivar parent parent instance of HdlStatement or nullptr
  * @ivar _inputs OrderedSet of input signals for this statement
  * @ivar _outputs OrderedSet of output signals for this statement
-
- * @ivar rank sum of numbers of used branches in statement, used as prefilter
+ *
+ * @ivar rank sum of numbers of used branches in statement, used as pre-filter
  *     for statement comparing
+ * @ivar sens the container for informations about sensitivity to nets
+ * @ivar __doc__ documentation string which will be added as a comment to target HDL
  *
  * @attention the sensitivity has to be discovered explicitly
  */
 class NETLISTDB_PUBLIC Statement: public OperationNode {
 public:
 	Statement * parent;
-
 	// IO of this statement
 	utils::OrderedSet<Net*> _inputs;
 	utils::OrderedSet<Net*> _outputs;
@@ -78,6 +79,9 @@ class NETLISTDB_PUBLIC Statement: public OperationNode {
 
 	size_t rank;
 
+	// __doc__ documentation string which will be added as a comment to target HDL
+	std::string __doc__;
+
 	Statement() :
 			parent(nullptr), rank(0) {
 	}
@@ -95,7 +99,7 @@ class NETLISTDB_PUBLIC Statement: public OperationNode {
 	/*
 	 * walk all direct child statements with specified function fn
 	 *
-	 * @param fn callback which is called on each node, if the function returns true the iteration is stoped
+	 * @param fn callback which is called on each node, if the function returns true the iteration is stopped
 	 * 		and the visit_child_stm returns
 	 * */
 	virtual void visit_child_stm(const std::function<bool(Statement &)> & fn) = 0;
@@ -165,11 +169,11 @@ class NETLISTDB_PUBLIC ComponentMap: public OperationNode {
  * There are multiple types of node in this directed graph
  * The signal, statement and FunctionCall (which represents also the operator usage)
  *
- * Each node has own list of neighbors. This is the case because the graph
+ * Each node has own list of neighbours. This is the case because the graph
  * is expected to change frequently and be larger than 10k nodes this representation
  * by linked list or connection matrix would not be efficient.
  *
- * Also for some nodes the order of neighbors does matter for some does not.
+ * Also for some nodes the order of neighbours does matter for some does not.
  * For example order of Signal endpoints does not matter. The order of Signals
  * in FunctionCall does.
  *
@@ -182,6 +186,8 @@ class NETLISTDB_PUBLIC Netlist {
 	std::vector<Net*> nets;
 	// all nets, statements, operators, etc.
 	std::vector<iNode*> nodes;
+	// __doc__ documentation string which will be added as a comment to target HDL
+	std::string __doc__;
 
 	Netlist(const Netlist & other) = delete;
 	Netlist(const std::string & name);
@@ -221,7 +227,7 @@ class NETLISTDB_PUBLIC Netlist {
 	~Netlist();
 };
 
-/** The net in Netlist instance also the hyperedge which connects
+/** The net in Netlist instance also the hyper-edge which connects
  *  the statements, expressions, etc.
  *
  *  @note The overloaded operators are building the expression in the netlist
@@ -256,6 +262,9 @@ class NETLISTDB_PUBLIC Net: public iNode {
 	// index used for last priority ordering
 	// represent the sequential number of the signal generated in parent context
 
+	// documentation string which will be added as a comment to target HDL
+	std::string __doc__;
+
 	Net(const Net & other) = delete;
 	// use methods from Netlist
 	Net(Netlist & ctx, hw_type::iHwType & t, const std::string & name,
@@ -374,9 +383,4 @@ class NETLISTDB_PUBLIC Net: public iNode {
 	Net & wrap_val_to_const_net(unsigned val);
 };
 
-
-
-
-
 }
-

include/netlistDB/serializer/serializer.h

@@ -23,6 +23,14 @@ class Serializer {
 	bool delete_io_after;
 	iSerializationIO & io;
 	Serializer(iSerializationIO & io, bool delete_io_after);
+
+	/*
+	 * Serialize the comment string
+	 *
+	 * @note may contain newlines etc.
+	 * */
+	virtual void serialize_comment(const std::string & comment) = 0;
+
 	/*
 	 * Serialize the type id
 	 *

include/netlistDB/serializer/verilog.h

@@ -64,6 +64,8 @@ class Verilog2001: public Serializer {
 	using Serializer::serialize_stm;
 	using Serializer::serialize_value;
 
+	virtual void serialize_comment(const std::string & comment) override;
+
 	virtual bool serialize_type_usage(const hw_type::iHwType & t);
 	virtual void serialize_value(
 			const typename hw_type::HwInt::value_type & val) override;

src/serializer/verilog.cpp

@@ -31,6 +31,19 @@ Verilog2001::Verilog2001(const std::string & root_dir,
 		Verilog2001(*new SerializeToFiles(root_dir), reserved_names, true) {
 }
 
+void Verilog2001::serialize_comment(const std::string & comment) {
+	if (comment.size()) {
+		auto & str = io.str();
+		indent() << "// ";
+		for (auto ch: comment) {
+			str << ch;
+			if (ch == '\n')
+				indent() << "// ";
+		}
+		str << endl;
+	}
+}
+
 void Verilog2001::print_array_indexes(const hw_type::iHwType * t, bool first) {
 	auto & str = io.str();
 	auto at = dynamic_cast<const hw_type::iHwType_array*>(t);
@@ -59,6 +72,7 @@ const hw_type::iHwType & Verilog2001::get_non_array_t(
 }
 
 void Verilog2001::serialize_net_def(const Net & n) {
+	serialize_comment(n.__doc__);
 	auto & str = io.str();
 	indent();
 	auto v_t = verilogTypeOfSig(n);

src/serializer/verilog_structural.cpp

@@ -24,6 +24,7 @@ void Verilog2001::serialize_direction(Direction d) {
 }
 
 void Verilog2001::serialize_io(const Net & io_net) {
+	serialize_comment(io_net.__doc__);
 	auto & str = io.str();
 	indent();
 	serialize_direction(io_net.direction);
@@ -56,7 +57,7 @@ void Verilog2001::serialize_module_head(const Netlist & netlist) {
 	//{{indent}}    ){% endif %}{% if ports|length >0 %}({{
 	//                     ports|join(',\n' + indent + '        ')}}
 	//{{indent}}    );{% endif %}
-
+	serialize_comment(netlist.__doc__);
 	indent() << "module "
 			<< name_scope.checkedName(netlist.name, &netlist, true);
 	// [TODO] parameters if present