The comments before each class and method are specially formatted, so that they can be automatically extracted by doxygen, and turned into the API documentation you can see on the website, e.g. at http://xapian.org/docs/apidoc/html/classXapian_1_1BM25Weight.html

Doxygen needs a comment to start ```/**``` or ```///``` or else it assumes it's just a normal comment, not a documentation comment.

The first line should be a *short* description - if there's much more to say than fits on a line, write a short summary, put a paragraph break, and then go into more detail.  Look at existing classes and methods for examples.

Something like ```Xapian::Weight subclass implementing the tf-idf weighting schemes.``` would be a good short description here.

Also, take care of whitespace around punctuation: "tf ,idf" -> "tf, idf" and "weight ." -> "weight."  It's a small detail, but small details are often quite important in programming, and if the documentation and/or comments look messy, people will probably pick that up subconsciously and assume the code is poor quality too.