Codechange: add missing @param and @return for linkgraph

src/linkgraph/demands.cpp

@@ -73,7 +73,7 @@ public:
 	 * nodes only accept anything if they also supply something. So if
 	 * undelivered_supply == 0 at the node there isn't any demand left either.
 	 * @param to Node to be checked.
-	 * @return If demand is left.
+	 * @return \c true iff demand is left.
 	 */
 	inline bool HasDemandLeft(const Node &to)
 	{
@@ -110,6 +110,7 @@ public:
 	/**
 	 * Get the effective supply of one node towards another one.
 	 * @param from The supplying node.
+	 * @return Effective supply.
 	 */
 	inline uint EffectiveSupply(const Node &from, const Node &)
 	{
@@ -120,6 +121,7 @@ public:
 	 * Check if there is any acceptance left for this node. In asymmetric distribution
 	 * nodes always accept as long as their demand > 0.
 	 * @param to The node to be checked.
+	 * @return \c true iff demand is left.
 	 */
 	inline bool HasDemandLeft(const Node &to) { return to.base.demand > 0; }
 };

src/linkgraph/linkgraph.cpp

@@ -34,6 +34,7 @@ LinkGraph::BaseNode::BaseNode(TileIndex xy, StationID st, uint demand)
 
 /**
  * Create an edge.
+ * @param dest_node The destination of this edge.
  */
 LinkGraph::BaseEdge::BaseEdge(NodeID dest_node)
 {

src/linkgraph/linkgraph.h

@@ -65,7 +65,11 @@ public:
 		void Restrict() { this->last_unrestricted_update = EconomyTime::INVALID_DATE; }
 		void Release() { this->last_restricted_update = EconomyTime::INVALID_DATE; }
 
-		/** Comparison operator based on \c dest_node. */
+		/**
+		 * Comparison operator based on \c dest_node.
+		 * @param rhs The right hand side of the comparison.
+		 * @return \c true iff our \c dest_node is smaller than the other's.
+		 */
 		bool operator <(const BaseEdge &rhs) const
 		{
 			return this->dest_node < rhs.dest_node;

src/linkgraph/linkgraph_gui.cpp

@@ -320,6 +320,7 @@ void LinkGraphOverlay::DrawContent(Point pta, Point ptb, const LinkProperties &c
 /**
  * Draw dots for stations into the smallmap. The dots' sizes are determined by the amount of
  * cargo produced there, their colours by the type of cargo produced.
+ * @param dpi The context to draw the overlay in.
  */
 void LinkGraphOverlay::DrawStationDots(const DrawPixelInfo *dpi) const
 {
@@ -445,7 +446,7 @@ void LinkGraphOverlay::SetCompanyMask(CompanyMask company_mask)
 	this->window->GetWidget<NWidgetBase>(this->widget_id)->SetDirty(this->window);
 }
 
-/** Make a number of rows with buttons for each company for the linkgraph legend window. */
+/** Make a number of rows with buttons for each company for the linkgraph legend window. @copydoc NWidgetFunctionType */
 std::unique_ptr<NWidgetBase> MakeCompanyButtonRowsLinkGraphGUI()
 {
 	return MakeCompanyButtonRows(WID_LGL_COMPANY_FIRST, WID_LGL_COMPANY_LAST, COLOUR_GREY, 3, STR_NULL);

src/linkgraph/linkgraph_gui.h

@@ -23,7 +23,10 @@
 struct LinkProperties {
 	LinkProperties() {}
 
-	/** Return the usage of the link to display. */
+	/**
+	 * Return the usage of the link to display.
+	 * @return The maximum of the actual and planned usage of the link.
+	 */
 	uint Usage() const { return std::max(this->usage, this->planned); }
 
 	CargoType cargo = INVALID_CARGO; ///< Cargo type of the link.
@@ -67,10 +70,16 @@ public:
 	/** Mark the linkgraph dirty to be rebuilt next time Draw() is called. */
 	void SetDirty() { this->dirty = true; }
 
-	/** Get a bitmask of the currently shown cargoes. */
+	/**
+	 * Get a bitmask of the currently shown cargoes.
+	 * @return The shown cargoes.
+	 */
 	CargoTypes GetCargoMask() { return this->cargo_mask; }
 
-	/** Get a bitmask of the currently shown companies. */
+	/**
+	 * Get a bitmask of the currently shown companies.
+	 * @return The shown companies.
+	 */
 	CompanyMask GetCompanyMask() { return this->company_mask; }
 
 protected:

src/linkgraph/linkgraphjob.h

@@ -178,6 +178,7 @@ public:
 	/**
 	 * Bare constructor, only for save/load. link_graph, join_date and actually
 	 * settings have to be brutally const-casted in order to populate them.
+	 * @param index Index into the LinkGraphJob pool.
 	 */
 	LinkGraphJob(LinkGraphJobID index) : LinkGraphJobPool::PoolItem<&_link_graph_job_pool>(index), link_graph(LinkGraphID::Invalid()), settings(_settings_game.linkgraph) {}
 
@@ -280,19 +281,34 @@ public:
 	Path(NodeID n, bool source = false);
 	virtual ~Path() = default;
 
-	/** Get the node this leg passes. */
+	/**
+	 * Get the node this leg passes.
+	 * @return The node.
+	 */
 	inline NodeID GetNode() const { return this->node; }
 
-	/** Get the overall origin of the path. */
+	/**
+	 * Get the overall origin of the path.
+	 * @return The origin node.
+	 */
 	inline NodeID GetOrigin() const { return this->origin; }
 
-	/** Get the parent leg of this one. */
+	/**
+	 * Get the parent leg of this one.
+	 * @return The parent of this leg.
+	 */
 	inline Path *GetParent() { return this->parent; }
 
-	/** Get the overall capacity of the path. */
+	/**
+	 * Get the overall capacity of the path.
+	 * @return The path's capacity.
+	 */
 	inline uint GetCapacity() const { return this->capacity; }
 
-	/** Get the free capacity of the path. */
+	/**
+	 * Get the free capacity of the path.
+	 * @return The path's capacity that isn't used.
+	 */
 	inline int GetFreeCapacity() const { return this->free_capacity; }
 
 	/**
@@ -316,19 +332,34 @@ public:
 		return Path::GetCapacityRatio(this->free_capacity, this->capacity);
 	}
 
-	/** Get the overall distance of the path. */
+	/**
+	 * Get the overall distance of the path.
+	 * @return The path's length.
+	 */
 	inline uint GetDistance() const { return this->distance; }
 
-	/** Reduce the flow on this leg only by the specified amount. */
+	/**
+	 * Reduce the flow on this leg only by the specified amount.
+	 * @param f The amount of flow to decrease by.
+	 */
 	inline void ReduceFlow(uint f) { this->flow -= f; }
 
-	/** Increase the flow on this leg only by the specified amount. */
+	/**
+	 * Increase the flow on this leg only by the specified amount.
+	 * @param f The amount of flow to increase by.
+	 */
 	inline void AddFlow(uint f) { this->flow += f; }
 
-	/** Get the flow on this leg. */
+	/**
+	 * Get the flow on this leg.
+	 * @return The accumulated flow.
+	 */
 	inline uint GetFlow() const { return this->flow; }
 
-	/** Get the number of "forked off" child legs of this one. */
+	/**
+	 * Get the number of "forked off" child legs of this one.
+	 * @return The number of children.
+	 */
 	inline uint GetNumChildren() const { return this->num_children; }
 
 	/**

src/linkgraph/mcf.cpp

@@ -348,6 +348,7 @@ void MultiCommodityFlow::CleanupPaths(NodeID source_id, PathVector &paths)
  * @param accuracy Accuracy of the calculation.
  * @param max_saturation If < UINT_MAX only push flow up to the given
  *                       saturation, otherwise the path can be "overloaded".
+ * @return The new flow.
  */
 uint MultiCommodityFlow::PushFlow(Node &node, NodeID to, Path *path, uint accuracy,
 		uint max_saturation)
@@ -595,6 +596,7 @@ MCF2ndPass::MCF2ndPass(LinkGraphJob &job) : MultiCommodityFlow(job)
  * @param y_anno Second value.
  * @param x Node id associated with the first value.
  * @param y Node id associated with the second value.
+ * @return \c true iff x is considered greater than y.
  */
 template <typename T>
 bool Greater(T x_anno, T y_anno, NodeID x, NodeID y)