[net-next PATCH] net: sched: document attach_default_qdiscs

[net-next PATCH] net: sched: document attach_default_qdiscs

[Phil Sutter]

The process of selecting an interface's default qdisc is not really
intuitive, at least because there are three different cases to consider.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 net/sched/sch_generic.c | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/net/sched/sch_generic.c b/net/sched/sch_generic.c
index cb5d4ad..d7eaa51 100644
--- a/net/sched/sch_generic.c
+++ b/net/sched/sch_generic.c
@@ -741,6 +741,18 @@ static void attach_one_default_qdisc(struct net_device *dev,
 	dev_queue->qdisc_sleeping = qdisc;
 }
 
+/**
+ *	attach_default_qdiscs - set qdiscs back to default
+ *	@dev: network device to attach to
+ *
+ * This function attaches the (configurable) default qdisc to
+ * an interface.
+ * The actual default depends: Non-MQ, physical interfaces
+ * get whatever default_qdisc_ops has been set to. Multiqueue
+ * interfaces get mq, which uses default_qdisc_ops for it's
+ * leaves. Finally, virtual interfaces unconditionally
+ * default to noqueue.
+ */
 static void attach_default_qdiscs(struct net_device *dev)
 {
 	struct netdev_queue *txq;
-- 
2.1.2

Re: [net-next PATCH] net: sched: document attach_default_qdiscs

[Cong Wang]

On Mon, Sep 14, 2015 at 8:31 AM, Phil Sutter <phil@nwl.cc> wrote:
> The process of selecting an interface's default qdisc is not really
> intuitive, at least because there are three different cases to consider.

It is a static function, not an API, so I don't think it is the right
place to document.

Maybe update default_qdisc description in Documentation/sysctl/net.txt?

Re: [net-next PATCH] net: sched: document attach_default_qdiscs

[Phil Sutter]

On Mon, Sep 14, 2015 at 03:07:42PM -0700, Cong Wang wrote:
> On Mon, Sep 14, 2015 at 8:31 AM, Phil Sutter <phil@nwl.cc> wrote:
> > The process of selecting an interface's default qdisc is not really
> > intuitive, at least because there are three different cases to consider.
> 
> It is a static function, not an API, so I don't think it is the right
> place to document.

So static functions should never be documented? I'm playing devil's
advocate, but still:

> Maybe update default_qdisc description in Documentation/sysctl/net.txt?

I don't think this is the right place for source code documentation. The
intended audience are users, and I wouldn't expect a developer to search
in there. On the other hand, that description would indeed benefit from
a review: Apart from omitting noqueue, it neither mentions leaf qdiscs.
I'll fix this.

Thanks, Phil

Re: [net-next PATCH] net: sched: document attach_default_qdiscs

[Cong Wang]

On Mon, Sep 14, 2015 at 3:42 PM, Phil Sutter <phil@nwl.cc> wrote:
> On Mon, Sep 14, 2015 at 03:07:42PM -0700, Cong Wang wrote:
>> Maybe update default_qdisc description in Documentation/sysctl/net.txt?
>
> I don't think this is the right place for source code documentation. The
> intended audience are users, and I wouldn't expect a developer to search
> in there. On the other hand, that description would indeed benefit from
> a review: Apart from omitting noqueue, it neither mentions leaf qdiscs.
> I'll fix this.
>

You are not just documenting the source code, you are documenting
a user-visible behavior. This is why I proposed net.txt.