fix various compiler warnings

Resort to gcc annotations in some cases, but avoid disabling whole
classes of warnings.
doc clarification