net.http: add documentation to http, method, server, and status (#17130)

vlib/net/http/http.v

@@ -11,7 +11,7 @@ const (
 	bufsize              = 1536
 )
 
-// FetchConfig holds configurations of fetch
+// FetchConfig holds configuration data for the fetch function.
 pub struct FetchConfig {
 pub mut:
 	url        string
@@ -31,6 +31,8 @@ pub mut:
 	allow_redirect         bool = true // whether to allow redirect
 }
 
+// new_request creates a new Request given the request `method`, `url_`, and
+// `data`.
 pub fn new_request(method Method, url_ string, data string) ?Request {
 	url := if method == .get && !url_.contains('?') { url_ + '?' + data } else { url_ }
 	// println('new req() method=$method url="$url" dta="$data"')
@@ -46,12 +48,12 @@ pub fn new_request(method Method, url_ string, data string) ?Request {
 	}
 }
 
-// get sends a GET HTTP request to the URL
+// get sends a GET HTTP request to the give `url`.
 pub fn get(url string) !Response {
 	return fetch(method: .get, url: url)
 }
 
-// post sends a POST HTTP request to the URL with a string data
+// post sends the string `data` as an HTTP POST request to the given `url`.
 pub fn post(url string, data string) !Response {
 	return fetch(
 		method: .post
@@ -61,7 +63,7 @@ pub fn post(url string, data string) !Response {
 	)
 }
 
-// post_json sends a POST HTTP request to the URL with a JSON data
+// post_json sends the JSON `data` as an HTTP POST request to the given `url`.
 pub fn post_json(url string, data string) !Response {
 	return fetch(
 		method: .post
@@ -71,7 +73,8 @@ pub fn post_json(url string, data string) !Response {
 	)
 }
 
-// post_form sends a POST HTTP request to the URL with X-WWW-FORM-URLENCODED data
+// post_form sends the map `data` as X-WWW-FORM-URLENCODED data to an HTTP POST request
+// to the given `url`.
 pub fn post_form(url string, data map[string]string) !Response {
 	return fetch(
 		method: .post
@@ -89,7 +92,8 @@ pub mut:
 	header Header
 }
 
-// post_multipart_form sends a POST HTTP request to the URL with multipart form data
+// post_multipart_form sends multipart form data `conf` as an HTTP POST
+// request to the given `url`.
 pub fn post_multipart_form(url string, conf PostMultipartFormConfig) !Response {
 	body, boundary := multipart_form_body(conf.form, conf.files)
 	mut header := conf.header
@@ -102,7 +106,7 @@ pub fn post_multipart_form(url string, conf PostMultipartFormConfig) !Response {
 	)
 }
 
-// put sends a PUT HTTP request to the URL with a string data
+// put sends string `data` as an HTTP PUT request to the given `url`.
 pub fn put(url string, data string) !Response {
 	return fetch(
 		method: .put
@@ -112,7 +116,7 @@ pub fn put(url string, data string) !Response {
 	)
 }
 
-// patch sends a PATCH HTTP request to the URL with a string data
+// patch sends string `data` as an HTTP PATCH request to the given `url`.
 pub fn patch(url string, data string) !Response {
 	return fetch(
 		method: .patch
@@ -122,17 +126,17 @@ pub fn patch(url string, data string) !Response {
 	)
 }
 
-// head sends a HEAD HTTP request to the URL
+// head sends an HTTP HEAD request to the given `url`.
 pub fn head(url string) !Response {
 	return fetch(method: .head, url: url)
 }
 
-// delete sends a DELETE HTTP request to the URL
+// delete sends an HTTP DELETE request to the given `url`.
 pub fn delete(url string) !Response {
 	return fetch(method: .delete, url: url)
 }
 
-// fetch sends an HTTP request to the URL with the given method and configurations
+// fetch sends an HTTP request to the `url` with the given method and configuration.
 pub fn fetch(config FetchConfig) !Response {
 	if config.url == '' {
 		return error('http.fetch: empty url')
@@ -158,13 +162,13 @@ pub fn fetch(config FetchConfig) !Response {
 	return res
 }
 
-// get_text sends a GET HTTP request to the URL and returns the text content of the response
+// get_text sends an HTTP GET request to the given `url` and returns the text content of the response.
 pub fn get_text(url string) string {
 	resp := fetch(url: url, method: .get) or { return '' }
 	return resp.body
 }
 
-// url_encode_form_data converts mapped data to an URL encoded string
+// url_encode_form_data converts mapped data to a URL encoded string.
 pub fn url_encode_form_data(data map[string]string) string {
 	mut pieces := []string{}
 	for key_, value_ in data {

vlib/net/http/method.v

@@ -18,6 +18,7 @@ pub enum Method {
 	patch
 }
 
+// str returns the string representation of the HTTP Method `m`.
 pub fn (m Method) str() string {
 	return match m {
 		.get { 'GET' }
@@ -32,6 +33,10 @@ pub fn (m Method) str() string {
 	}
 }
 
+// method_from_str returns the corresponding Method enum field
+// given a string `m`, e.g. `'GET'` would return Method.get.
+//
+// Currently, the default value is Method.get for unsupported string value.
 pub fn method_from_str(m string) Method {
 	return match m {
 		'GET' { Method.get }

vlib/net/http/server.v

@@ -34,6 +34,8 @@ pub mut:
 	accept_timeout time.Duration = 30 * time.second
 }
 
+// listen_and_serve listens on the server port `s.port` over TCP network and
+// uses `s.parse_and_respond` to handle requests on incoming connections with `s.handler`.
 pub fn (mut s Server) listen_and_serve() {
 	if s.handler is DebugHandler {
 		eprintln('Server handler not set, using debug handler')
@@ -68,19 +70,20 @@ pub fn (mut s Server) listen_and_serve() {
 	}
 }
 
-// stop signals the server that it should not respond anymore
+// stop signals the server that it should not respond anymore.
 [inline]
 pub fn (mut s Server) stop() {
 	s.state = .stopped
 }
 
-// close immediatly closes the port and signals the server that it has been closed
+// close immediatly closes the port and signals the server that it has been closed.
 [inline]
 pub fn (mut s Server) close() {
 	s.state = .closed
 	s.listener.close() or { return }
 }
 
+// status indicates whether the server is running, stopped, or closed.
 [inline]
 pub fn (s &Server) status() ServerStatus {
 	return s.state
@@ -112,7 +115,7 @@ fn (mut s Server) parse_and_respond(mut conn net.TcpConn) {
 }
 
 // DebugHandler implements the Handler interface by echoing the request
-// in the response
+// in the response.
 struct DebugHandler {}
 
 fn (d DebugHandler) handle(req Request) Response {

vlib/net/http/status.v

@@ -76,6 +76,8 @@ pub enum Status {
 	network_authentication_required = 511
 }
 
+// status_from_int returns the corresponding enum field of Status
+// given the `code` in integer value.
 pub fn status_from_int(code int) Status {
 	return match code {
 		100 { Status.cont }
@@ -154,6 +156,7 @@ pub fn status_from_int(code int) Status {
 	}
 }
 
+// str returns the string representation of Status `code`.
 pub fn (code Status) str() string {
 	return match code {
 		.cont { 'Continue' }