Add apidoc-lint target into CI

* Made a module comment mandatory except for graphql/core.
* Added apidoc-lint dependency to test, bench, apidoc, coverage goals.
* Fixed current ldoc warnings.
* Added ldoc installing into test, pack and coverage environments.

Author: Totktonada

Makefile

@@ -23,16 +23,23 @@ lint:
 		test/*.lua \
 		--no-redefined --no-unused-args
 
+.PHONY: apidoc-lint
+apidoc-lint:
+	! ldoc -d doc/apidoc-lint-tmp graphql --all -f markdown 2>&1 >/dev/null | \
+		grep -v -e 'graphql/core.*: no module() call found; no initial doc comment$$' \
+		-e ': contains no items$$'
+	rm -rf doc/apidoc-lint-tmp
+
 .PHONY: test
-test: lint
+test: lint apidoc-lint
 	virtualenv -p python2.7 ./.env-2.7
 	. ./.env-2.7/bin/activate && \
 		pip install -r ./test-run/requirements.txt && \
 		pip install tarantool && \
 		cd test && ./test-run.py
 
 .PHONY: bench
-bench: lint
+bench: lint apidoc-lint
 	virtualenv -p python2.7 ./.env-2.7
 	. ./.env-2.7/bin/activate && \
 		pip install -r ./test-run/requirements.txt && \
@@ -51,14 +58,8 @@ pure-bench:
 clean:
 	rm -rf test/var luacov.stats.out luacov.report.out
 
-.PHONY: apidoc-lint
-apidoc-lint:
-	! ldoc -d doc/apidoc-lint-tmp graphql --all -f markdown 2>&1 >/dev/null | \
-		grep -v ': no module() call found; no initial doc comment$$\|: contains no items$$'
-	rm -rf doc/apidoc-lint-tmp
-
 .PHONY: apidoc
-apidoc:
+apidoc: apidoc-lint
 	ldoc -d doc/apidoc graphql --all -f markdown
 	# fix navigation panel width
 	sed -i -e 's/: 14em;/: 24em;/' doc/apidoc/ldoc.css
@@ -77,7 +78,7 @@ rpm:
 	   ./3rd_party/packpack/packpack
 
 .PHONY: coverage
-coverage: lint
+coverage: lint apidoc-lint
 	virtualenv -p python2.7 ./.env-2.7
 	. ./.env-2.7/bin/activate && \
 		pip install -r ./test-run/requirements.txt && \

graphql/accessor_general.lua

@@ -260,7 +260,7 @@ local function check_deadline_clock(qcontext)
 end
 
 --- Perform unflatten, skipping, filtering, limiting of objects. This is the
---- core of the `select_internal` function.
+--- core of the @{prepare_select_internal} function.
 ---
 --- @tparam table self accessor_general instance
 ---
@@ -680,12 +680,13 @@ end
 
 --- Insert an object.
 ---
---- Parameters are the same as for @{select_internal}.
+--- Parameters are the same as for @{prepare_select_internal}.
 ---
 --- @treturn table list of a single object we inserted
 ---
---- We can just return the object and omit select_internal() call, because we
---- forbid any filters/args that could affect the result.
+--- We can just return the object and omit prepare_select_internal() /
+--- invoke_select_internal() calls, because we forbid any filters/args that
+--- could affect the result.
 local function insert_internal(self, collection_name, from, filter, args, extra)
     local object = extra.extra_args.insert
     if object == nil then return nil end
@@ -720,7 +721,8 @@ end
 
 --- Update an object.
 ---
---- Same-named parameters meaning is the same as for @{select_internal}.
+--- Same-named parameters meaning is the same as for
+--- @{prepare_select_internal}.
 ---
 --- @tparam table self the data accessor instance
 ---
@@ -757,7 +759,7 @@ end
 
 --- Delete an object.
 ---
---- Corresponding parameters are the same as for @{select_internal}.
+--- Corresponding parameters are the same as for @{prepare_select_internal}.
 ---
 --- @tparam table self
 ---

graphql/accessor_shard_cache.lua

@@ -1,3 +1,5 @@
+--- Request a data in a batch and save them to a cache.
+
 local json = require('json')
 local utils = require('graphql.utils')
 local shard = utils.optional_require('shard')

graphql/bfs_executor.lua

@@ -491,7 +491,7 @@ end
 ---         fragmentMap = fragmentMap,
 ---     }
 ---
---- @tparam table qcontext the following options:
+--- @tparam table opts the following options:
 ---
 --- * is_item_cache_only
 --- * qcontext: query-local storage for various purposes
@@ -636,6 +636,9 @@ local function filter_object(object, object_type, selections, context, opts)
     }
 end
 
+--- Select fields from objects in a list, create prepared resolve functions.
+---
+--- See @{filter_object} for the API and a description.
 filter_object_list = function(object_list, object_type, selections, context,
         opts)
     local opts = opts or {}

graphql/convert_schema/helpers.lua

@@ -1,3 +1,5 @@
+--- Auxiliary functions needed for converting schemas.
+
 local utils = require('graphql.utils')
 local check = utils.check
 

graphql/convert_schema/init.lua

@@ -1,3 +1,5 @@
+--- Convert an extended avro-schema (collections) to a GraphQL schema.
+
 local schema = require('graphql.convert_schema.schema')
 
 local convert_schema = {}

graphql/convert_schema/schema.lua

@@ -1,4 +1,4 @@
---- Convert extended avro-schema (collections) to GraphQL schema.
+--- Convert an extended avro-schema (collections) to a GraphQL schema.
 
 local log = require('log')
 local core_types = require('graphql.core.types')

graphql/convert_schema/union.lua

@@ -1,3 +1,6 @@
+--- Convert an avro-schema union type to a GraphQL Union of InputUnion
+--- (non-standard) type.
+
 local yaml = require('yaml')
 local core_types = require('graphql.core.types')
 local avro_helpers = require('graphql.avro_helpers')

graphql/db_schema_helpers.lua

@@ -1,3 +1,5 @@
+--- Auxiliary functions to work with extended avro-schemas (collections).
+
 local utils = require('graphql.utils')
 local check = utils.check
 

graphql/error_codes.lua

@@ -1,3 +1,5 @@
+--- GraphQL module error codes.
+
 local error_codes = {}
 
 error_codes.TYPE_MISMATCH = 1

graphql/expressions.lua

@@ -1,3 +1,5 @@
+--- C-style expressions parser and executor.
+
 local lpeg = require('lulpeg')
 local utils = require('graphql.utils')
 

graphql/expressions/constant_propagation.lua

@@ -1,3 +1,5 @@
+--- Constant propagation optimization pass.
+
 local expressions = require('graphql.expressions')
 
 local constant_propagation = {}
@@ -19,7 +21,7 @@ end
 ---     value = <...> (of any type),
 --- }
 ---
---- @tparam table current AST node (e.g. root node)
+--- @tparam table node current AST node (e.g. root node)
 ---
 --- @tparam table context table of the following values:
 ---
@@ -140,7 +142,7 @@ end
 ---     value = <...> (of any type),
 --- }
 ---
---- @tparam table expression
+--- @tparam table expr expression
 ---
 --- @tparam table context table of the following values:
 ---

graphql/extend_ast.lua

@@ -1,3 +1,5 @@
+--- Extend GraphQL query AST with compiled expressions.
+
 local expressions = require('graphql.expressions')
 
 local extend_ast = {}

graphql/request_batch.lua

@@ -1,3 +1,5 @@
+--- Class representing a batch of similar requests.
+
 local utils = require('graphql.utils')
 
 local request_batch = {}

graphql/server/server.lua

@@ -1,3 +1,5 @@
+--- Serve GraphQL requests and the GraphiQL web interface via HTTP.
+
 local fio = require('fio')
 local graphql_utils = require('graphql.utils')
 local utils = require('graphql.server.utils')

graphql/server/utils.lua

@@ -1,3 +1,5 @@
+--- Auxiliary functions for graphql.server.
+
 local fio = require('fio')
 
 local utils = {}

graphql/statistics.lua

@@ -1,3 +1,5 @@
+--- Count various statistics about a query.
+
 local utils = require('graphql.utils')
 local error_codes = require('graphql.error_codes')
 

graphql/storage.lua

@@ -1,3 +1,5 @@
+--- Functions to be exposed from shard storage nodes.
+
 local log = require('log')
 local json = require('json')
 -- local yaml = require('yaml')

rpm/prebuild.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+set -exu  # Strict shell (w/o -o pipefail)
+
+sudo yum -y install lua-devel luarocks
+sudo luarocks install ldoc

tools/ubuntu.trusty.prepare.sh

@@ -27,6 +27,7 @@ tarantoolctl rocks install shard ${SHARD_VERSION:-}
 tarantoolctl rocks install avro-schema ${AVRO_SCHEMA:-}
 
 sudo luarocks install luacheck
+sudo luarocks install ldoc
 sudo pip install virtualenv
 
 # luacov, cluacov, luacov-coveralls and dependencies