generate api reference documents by doxygen

src/php/bin/php_extension_doxygen_filter.awk

@@ -0,0 +1,172 @@
+# Copyright 2020 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+BEGIN {
+    namespace = "Grpc";
+    className = "";
+    classDocComment = "";
+    delete methods; # methods[method][doc|args|static]
+    delete constants; # constants[i][name|doc]
+    constantsCount = 0;
+
+    #  * class className
+    classLineRegex = "^ \\* class (\\S+)$";
+    # @param type name [= default]
+    paramLineRegex = "^.*@param\\s+\\S+\\s+(\\$\\S+(\\s+=\\s+\\S+)?)\\s+.*$";
+    # PHP_METHOD(class, function)
+    phpMethodLineRegex = "^PHP_METHOD\\((\\S+),\\s*(\\S+)\\).*$";
+
+    # PHP_ME(class, function, arginfo, flags)
+    phpMeLineRegex = "^\\s*PHP_ME\\((\\S+),\\s*(\\S+),.*$";
+
+    # REGISTER_LONG_CONSTANT("namespace\\constant", grpcConstant, ..)
+    phpConstantLineRegs = "^\\s*REGISTER_LONG_CONSTANT\\(\"Grpc\\\\\\\\(\\S+)\",.*$";
+
+    error = "";
+
+    # extension testing methods
+    hideMethods["Channel::getChannelInfo"] = 1;
+    hideMethods["Channel::cleanPersistentList"] = 1;
+    hideMethods["Channel::getPersistentList"] = 1;
+
+}
+
+# '/**' document comment start
+/^\s*\/\*\*/ {
+    inDocComment = 1;
+    docComment = "";
+    delete args;
+    argsCount = 0;
+}
+
+# collect document comment
+inDocComment==1 {
+    docComment = docComment"\n"$0
+}
+
+# class document, must match ' * class <clasName>'
+inDocComment==1 && $0 ~ classLineRegex {
+    className = gensub(classLineRegex, "\\1", "g");
+}
+
+# end of class document
+inDocComment==1 && /\*\// && classDocComment == "" {
+    classDocComment = docComment;
+    docComment = "";
+}
+
+# param line
+inDocComment==1 && $0 ~ paramLineRegex {
+    arg = gensub(paramLineRegex, "\\1", "g");
+    args[argsCount]=arg;
+    argsCount++;
+}
+
+# '*/' document comment end
+inDocComment==1 && /\*\// {
+    inDocComment = 0;
+}
+
+# PHP_METHOD
+$0 ~ phpMethodLineRegex {
+    class = gensub(phpMethodLineRegex, "\\1", "g");
+    if (class != className) {
+        error = "ERROR: Missing or mismatch class names, in class comment block: " \
+          className ", in PHP_METHOD: " class;
+        exit;
+    };
+
+    method = gensub(phpMethodLineRegex, "\\2", "g");
+    methods[method]["doc"] = docComment;
+    for (i in args) {
+        methods[method]["args"][i] = args[i];
+    }
+    docComment = "";
+}
+
+# PHP_ME(class, function,...
+$0 ~ phpMeLineRegex {
+    inPhpMe = 1;
+
+    class = gensub(phpMeLineRegex, "\\1", "g");
+    if (class != className) {
+        error = "ERROR: Missing or mismatch class names, in class comment block: " \
+          className ", in PHP_ME: " class;
+        exit;
+    };
+    method = gensub(phpMeLineRegex, "\\2", "g");
+}
+
+# ZEND_ACC_STATIC
+inPhpMe && /ZEND_ACC_STATIC/ { 
+    methods[method]["static"] = 1;
+}
+
+# closing bracet of PHP_ME(...)
+iinPhpMe && /\)$/ {
+    inPhpMe = 0;
+}
+
+# REGISTER_LONG_CONSTANT(constant, ...
+$0 ~ phpConstantLineRegs {
+    inPhpConstant = 1;
+    constant = gensub(phpConstantLineRegs, "\\1", "g");
+    constants[constantsCount]["name"] = constant;
+    constants[constantsCount]["doc"] = docComment;
+    constantsCount++;
+}
+
+# closing bracet of PHP_ME(...)
+inPhpConstant && /\)\s*;\s*$/ {
+    inPhpConstant = 0;
+    docComment = "";
+}
+
+END {
+    if (error) {
+        print error > "/dev/stderr";
+        exit 1;
+    }
+
+    print "<?php\n"
+    print "namespace " namespace "{";
+
+    if (className != "") {
+        print classDocComment
+        print "class " className " {";
+        for (m in methods) {
+            if (hideMethods[className"::"m]) continue;
+
+            print methods[m]["doc"];
+            printf "public"
+            if (methods[m]["static"]) printf " static"
+            printf " function " m "("
+            if (isarray(methods[m]["args"])) {
+                printf methods[m]["args"][0];
+                for (i = 1; i < length(methods[m]["args"]); i++) {
+                    printf ", " methods[m]["args"][i];
+                }
+            }
+            print ") {}";
+        }
+        print "\n}";
+    }
+
+    for (i in constants) {
+        print constants[i]["doc"];
+        print "const " constants[i]["name"] " = 0;";
+    }
+
+    print "\n}";
+}

src/php/bin/php_extension_to_php_doc.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Copyright 2020 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -euo pipefail
+
+if ! command -v gawk > /dev/null; then
+    >&2 echo "ERROR: 'gawk' not installed"
+    exit 1
+fi
+
+cd $(dirname $0)
+
+COMMAND="${1:-}"
+
+# parse class and methods
+for FILENAME in call_credentials.c call.c channel.c channel_credentials.c \
+                server_credentials.c server.c timeval.c ; do
+    CLASS_NAME=$(sed -r 's/(^|_)(\w)/\U\2/g' <<< "${FILENAME%.*}")
+    if [[ "$COMMAND" == "generate" ]]; then
+        echo Generating lib/Grpc/$CLASS_NAME.php ...
+        gawk -f php_extension_doxygen_filter.awk ../ext/grpc/$FILENAME \
+            > ../lib/Grpc/$CLASS_NAME.php
+    elif [[ "$COMMAND" == "cleanup" ]]; then
+        rm ../lib/Grpc/$CLASS_NAME.php
+    else
+        >&2 echo "Missing or wrong command. Usage: '$(basename $0) <generate|cleanup>'"
+        exit 1
+    fi
+done
+
+# parse constants
+if [[ "$COMMAND" == "generate" ]]; then
+    echo Generating lib/Grpc/Constants.php ...
+    gawk -f php_extension_doxygen_filter.awk ../ext/grpc/php_grpc.c \
+        > ../lib/Grpc/Constants.php
+elif [[ "$COMMAND" == "cleanup" ]]; then
+    rm ../lib/Grpc/Constants.php
+fi

templates/tools/dockerfile/test/sanity/Dockerfile.template

@@ -19,7 +19,7 @@
 
   #========================
   # Sanity test dependencies
-  RUN apt-get update && apt-get -t buster install -y python3.7 python3-all-dev
+  RUN apt-get update && apt-get -t buster install -y python3.7 python3-all-dev gawk
   RUN curl https://bootstrap.pypa.io/get-pip.py | python3.7
 
   # Make Python 3.7 the default Python 3 version

templates/tools/doxygen/Doxyfile.php.include

@@ -0,0 +1,31 @@
+
+<%namespace import="doxy_base" file="Doxyfile.base"/>
+<%def name="gen_doxyfile(internal)">
+<%
+  import itertools
+  import glob
+  import os
+  import fnmatch
+  import subprocess
+  
+  srcdoc = []
+  for dirpath, dirnames, filenames in os.walk('src/php'):
+    for filename in filenames:
+      if os.path.splitext(filename)[1] == '.md':
+        srcdoc.append(os.path.join(dirpath, filename))
+
+  subprocess.check_call(["src/php/bin/php_extension_to_php_doc.sh", "generate"])
+
+  version = settings.php_version
+  doxy_input = ' \\\n'.join(sorted(set(
+        itertools.chain(
+            glob.glob('src/php/lib/Grpc/*.php'),
+            glob.glob('src/php/lib/Grpc/Internal/*.php') if internal else [],
+            glob.glob('doc/*.md'),
+            srcdoc)
+    )))
+
+  subprocess.check_call(["src/php/bin/php_extension_to_php_doc.sh", "cleanup"])
+%>
+${doxy_base("PHP", version, doxy_input, internal)}
+</%def> 

templates/tools/doxygen/Doxyfile.php.template

@@ -0,0 +1,6 @@
+%YAML 1.2
+--- |
+  <%namespace file="Doxyfile.php.include" import="gen_doxyfile"/>\
+  ${gen_doxyfile(False)}
+  # Do not include values of 'GRPC\XXXX' constants
+  MAX_INITIALIZER_LINES = 0

tools/distrib/check_copyright.py

@@ -79,6 +79,9 @@ _EXEMPT = frozenset((
     'examples/python/route_guide/route_guide_pb2.py',
     'examples/python/route_guide/route_guide_pb2_grpc.py',
 
+    # Generated doxygen config file
+    'tools/doxygen/Doxyfile.php',
+
     # An older file originally from outside gRPC.
     'src/php/tests/bootstrap.php',
     # census.proto copied from github

tools/dockerfile/test/sanity/Dockerfile

@@ -67,7 +67,7 @@ RUN apt-get update && apt-get -y install libgflags-dev libgtest-dev libc++-dev c
 
 #========================
 # Sanity test dependencies
-RUN apt-get update && apt-get -t buster install -y python3.7 python3-all-dev
+RUN apt-get update && apt-get -t buster install -y python3.7 python3-all-dev gawk
 RUN curl https://bootstrap.pypa.io/get-pip.py | python3.7
 
 # Make Python 3.7 the default Python 3 version

tools/doxygen/run_doxygen.sh

@@ -19,9 +19,13 @@ set -ex
 # change to grpc repo root
 cd $(dirname $0)/../..
 
-for i in core c++ core.internal c++.internal objc objc.internal
+src/php/bin/php_extension_to_php_doc.sh generate
+
+for i in core c++ core.internal c++.internal objc objc.internal php
 do
 	rm -rf doc/ref/$i
 	mkdir -p doc/ref/$i
 	doxygen tools/doxygen/Doxyfile.$i
 done
+
+src/php/bin/php_extension_to_php_doc.sh cleanup