Re: [MERGE] Initial netfilter mark patch for comment

> * My understanding is that class data members and public class methods
> should be documented in the header. Others should be documented in the
> .cc files. You may want to double check this rule with Amos before
> moving comments though.
>
> * Many Qos data members are not documented, including new ones.
>

I have documented all the functions and class data members. Could you
clarify whether *every* variable should be documented with doxygen
comments (including short-lived temporary ones within functions), or
just those that are part of classes/structs?

For example, should 'tos' in the function below have doxygen comments?

int
Ip::Qos::doTosLocalMiss(const int fd, const HierarchyLogEntry *hier)
{
    unsigned char tos = 0;
    if (Ip::Qos::TheConfig.tos_sibling_hit && hier->code==SIBLING_HIT ) {
        tos = Ip::Qos::TheConfig.tos_sibling_hit;
        debugs(33, 2, "QOS: Sibling Peer hit with hier code=" << hier->code << ", TOS=" << (int)tos);
    } else if (Ip::Qos::TheConfig.tos_parent_hit && hier->code==PARENT_HIT) {
        tos = Ip::Qos::TheConfig.tos_parent_hit;
        debugs(33, 2, "QOS: Parent Peer hit with hier code=" << hier->code << ", TOS=" << (int)tos);
    } else if (Ip::Qos::TheConfig.preserve_miss_tos && Ip::Qos::TheConfig.preserve_miss_tos_mask) {
        tos = fd_table[fd].upstreamTOS & Ip::Qos::TheConfig.preserve_miss_tos_mask;
        debugs(33, 2, "QOS: Preserving TOS on miss, TOS=" << int(tos));
    }
    return setSockTos(fd, tos);
}

Thanks,

Andy
Received on Sat Aug 21 2010 - 22:42:40 MDT