Publish generated API documentation

[boweeb]

The occasion for writing this feat request was specifically related to configuration directives. I was wondering about max-ttl and could only find brief commentary on the Cache Configuration page.

Which values are valid? The 5s example is clearly "5 seconds". Does it support 5m or 5seconds? How does it interpret 5 (no suffix)? What about 0? I could see that meaning "off (always fetch)" or "indefinite (never fetch)" -- there's precedent for both semantic meanings in the wild.

Also, what settings are even available? I can find the Config struct in the source, but I've not found an enumeration of these config keys in any published documentation.

The above is just an example -- although it would be appreciated, I'm not asking for feedback about max-ttl here (and I plan on figuring it out by reading the source). Rather, I believe that this scenario (and more) would be naturally covered by auto-generated API documentation.

I hail from the Python ecosystem where the de facto solution is Sphinx, commonly paired with something like pdoc, autodoc, doxygen, etc. I'm sure Go must have similar tooling available. With proper docstrings and a pipeline, it would be effortless to keep these generated docs in sync.

[rs]

Is this what you are looking for?

nextdns config set -h
Usage of  nextdns config set:
  -auto-activate
    	Run activate at startup and deactivate on exit.
  -bogus-priv
    	Bogus private reverse lookups.
    	
    	All reverse lookups for private IP ranges (ie 192.168.x.x, etc.) are
    	answered with "no such domain" rather than being forwarded upstream.
    	The set of prefixes affected is the list given in RFC6303, for IPv4
    	and IPv6. (default true)
  -cache-max-age duration
    	If set to greater than 0, a cached entry will be considered stale after
    	this duration, even if the record's TTL is higher.
  -cache-size string
    	Set the size of the cache in byte. Use 0 to disable caching. The value
    	can be expressed with unit like kB, MB, GB. The cache is automatically
    	flushed when the pointed profile is updated. (default "0")
  -config value
    	deprecated, use -profile instead
  -config-file string
    	Custom path to configuration file.
  -control string
    	Address to the control socket. (default "/var/run/nextdns.sock")
  -debug
    	Enable debug logs.
  -detect-captive-portals
    	Automatic detection of captive portals and fallback on system DNS to
    	allow the connection to establish.
    	
    	Beware that enabling this feature can allow an attacker to force nextdns
    	to disable DoH and leak unencrypted DNS traffic.
  -discovery-dns string
    	The address of a DNS server to be used to discover client names.
    	If not defined, the address learned via DHCP will be used. This setting
    	is only active if report-client-info is set to true.
  -forwarder value
    	A DNS server to use for a specified domain.
    	
    	Forwarders can be defined to send proxy DNS traffic to an alternative
    	DNS upstream resolver for specific domains. The format of this parameter
    	is [DOMAIN=]SERVER_ADDR[,SERVER_ADDR...].
    	
    	A SERVER_ADDR can ben either an IP[:PORT] for DNS53 (unencrypted UDP,
    	TCP), or a HTTPS URL for a DNS over HTTPS server. For DoH, a bootstrap
    	IP can be specified as follow: https://dns.nextdns.io#45.90.28.0.
    	Several servers can be specified, separated by commas to implement
    	failover.
    	This parameter can be repeated. The first match wins.
  -hardened-privacy
    	Deprecated.
  -listen value
    	Listen address for UDP DNS proxy server.
  -log-queries
    	Log DNS queries.
  -max-inflight-requests uint
    	Maximum number of inflight requests handled by the proxy. No additional
    	requests will not be answered after this threshold is met. Increasing
    	this value can reduce latency in case of burst of requests but it can
    	also increase significantly memory usage. (default 256)
  -max-ttl duration
    	If set to greater than 0, defines the maximum TTL value that will be
    	handed out to clients. The specified maximum TTL will be given to
    	clients instead of the true TTL value if it is lower. The true TTL
    	value is however kept in the cache to evaluate cache entries
    	freshness. This is best used in conjunction with the cache to force
    	clients not to rely on their own cache in order to pick up
    	profile changes faster.
  -mdns string
    	Enable mDNS to discover client information and serve mDNS learned names over DNS.
    	Use "all" to listen on all interface or an interface name to limit mDNS on a
    	specific network interface. Use "disabled" to disable mDNS altogether. (default "all")
  -profile value
    	NextDNS custom profile id.
    	
    	The profile id can be prefixed with a condition that is match for
    	each query:
    	* 10.0.3.0/24=abcdef: A CIDR can be used to restrict a profile to
    	  a subnet.
    	* 00:1c:42:2e:60:4a=abcdef: A MAC address can be used to restrict
    	  profile to a specific host on the LAN.
    	
    	This parameter can be repeated. The first match wins.
  -report-client-info
    	Embed clients information with queries.
  -setup-router
    	Automatically configure NextDNS for a router setup.
    	Common types of router are detected to integrate gracefully. Changes
    	applies are undone on daemon exit. The listen option is ignored when
    	this option is used.
  -timeout duration
    	Maximum duration allowed for a request before failing. (default 5s)
  -use-hosts
    	Lookup /etc/hosts before sending queries to upstream resolver. (default true)

[boweeb]

@rs -- It's not quite clear if you're asking if this is representative of the info I had in mind or if you're implying the CLI help system is adequate (to cover this feat request). If the former, then yes -- that info but collected and pushed to something like readthedocs.com or wherever.

If the latter, then I'm happy to concede. This is a "nice-to-have" feature request, not a bug report. I found what I needed eventually (via the CLI help flags, as you've demonstrated). In the workflows I'm accustomed to, it's often handy to have (and find) this content in an open browser tab. I figured it couldn't hurt to ask, but I also want to be respectful of the project's time, resources, and priorities.