Document ProductInfoHeaderValue constructors

[svick]

I'm sometimes making HTTP requests to various APIs. Quite often, they require specifying the User-Agent header. To do that with HttpClient, I have to create ProductInfoHeaderValue, e.g.:

ProductInfoHeaderValue value = …;
var client = new HttpClient { DefaultRequestHeaders = { UserAgent = { value } } };

My problem is that creating valid ProductInfoHeaderValue is not obvious and the documentation for its constructors does not explain which constructor I should use or what are the requirements for the string parameters.

As an example, if I try new ProductInfoHeaderValue("svick's awesome tool"), it throws "FormatException: The format of value 'svick's awesome tool' is invalid." This doesn't help me figure out what the valid values are, which is why I think documenting this is important.

This article explains the rules for User-Agent values and might be helpful when resolving this issue.

[rpetrusha]

Thanks for opening this issue, @svick. At a minimum, making this documentation usable requires:

• Disambiguating the three constructor overloads (they all have identical descriptions!).
• Defining what a valid string value is.
  We'll add this to be addressed in quarter 3, and also add it to the project for community contributors.

[mairaw]

@davidsh is this something you could help with?