From 60bcf84ddaa281f1e803b11a7db77d8a7f8c58c6 Mon Sep 17 00:00:00 2001 From: Yasuo Ohgaki Date: Sun, 26 Jan 2014 18:28:21 +0900 Subject: [PATCH 1/4] Update source docs --- CODING_STANDARDS | 25 ++++++++++++++++++++++--- README.EXTENSIONS | 8 ++++++++ README.EXT_SKEL | 30 ++++++++++++++++++++++++------ README.SUBMITTING_PATCH | 8 ++++++++ 4 files changed, 62 insertions(+), 9 deletions(-) diff --git a/CODING_STANDARDS b/CODING_STANDARDS index 7a0562e6ca9..fccc2b873db 100644 --- a/CODING_STANDARDS +++ b/CODING_STANDARDS @@ -82,7 +82,7 @@ Exceptions: library may need to control or free the memory, or when the memory in question needs to survive between multiple requests. -Naming Conventions +User Functions/Methods Naming Conventions ------------------ 1. Function names for user-level functions should be enclosed with in @@ -163,6 +163,25 @@ Naming Conventions 'foobar' 'foo_bar' +Internal Function Naming Convensions +---------------------- + +1. Exposed module API must be named 'php_modulename_function()' to avoid + symbol collision. They should be in lowercase, with words underscore + delimited. Exposed API must be defined in 'php_modulename.h'. + + PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS); + + Unexposed module function should be static and should not be defined in + 'php_modulename.h'. + + static int php_session_destroy(TSRMLS_D) + +2. Main module source file must be named 'modulename.c'. + +3. Header file that are used by other sources must be named 'php_modulename.h'. + + Syntax and indentation ---------------------- @@ -181,9 +200,9 @@ Syntax and indentation of PHP or one of its standard modules, please maintain the K&R style. This applies to just about everything, starting with indentation and comment styles and up to function declaration - syntax. Also see Indentstyle_. + syntax. Also see Indentstyle. -.. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html + Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html 3. Be generous with whitespace and braces. Keep one empty line between the variable declaration section and the statements in a block, as well as diff --git a/README.EXTENSIONS b/README.EXTENSIONS index 06d6cdd85f2..e802af8329a 100644 --- a/README.EXTENSIONS +++ b/README.EXTENSIONS @@ -1,3 +1,11 @@ +This file describes extension module API details. Refer to +README.EXT_SKEL to create extension skeleton files. Refer to +Hacker's Guide for PHP internals. + +http://www.php.net/manual/en/internals2.php + + + Between PHP 4.0.6 and 4.1.0, the Zend module struct changed in a way that broke both source and binary compatibility. If you are maintaining a third party extension, here's how to update it: diff --git a/README.EXT_SKEL b/README.EXT_SKEL index d44fcc5c6a9..20b684ddfa6 100644 --- a/README.EXT_SKEL +++ b/README.EXT_SKEL @@ -45,12 +45,29 @@ HOW TO USE IT --proto=filename. +SOURCE AND HEADER FILE NAME + + ./ext_skel generates 'module_name.c' and 'php_module_name.h' as main source + and header files. Keep these names. + + Module functions (User functions) must be named + + module_name_function() + + When you need to expose module functions to other modules, expose functions + strictly needed by others. Exposed internal function must be named + + php_module_name_function() + + See also CODING_STANDARDS. + + FORMAT OF FUNCTION DEFINITIONS FILE All the definitions must be on one line. In it's simplest form, it's just the function name, e.g. - my_function + module_name_function but then you'll be left with an almost empty function body without any argument handling. @@ -72,8 +89,9 @@ FORMAT OF FUNCTION DEFINITIONS FILE An example: - my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st + module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]]) + Arguments arg1 and arg2 is required. Arguments arg3 and arg4 are optional. If possible, the function definition should also contain it's return type @@ -133,15 +151,15 @@ EXAMPLE The following _one_ line - bool my_drawtext(resource image, string text, resource font, int x, int y [, int color]) + bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) will create this function definition for you (note that there are a few question marks to be replaced by you, and you must of course add your own value definitions too): -/* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y [, int color]) +/* {{{ proto bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) */ -PHP_FUNCTION(my_drawtext) +PHP_FUNCTION(module_name_drawtext) { char *text = NULL; int argc = ZEND_NUM_ARGS(); @@ -164,7 +182,7 @@ PHP_FUNCTION(my_drawtext) ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id); } - php_error(E_WARNING, "my_drawtext: not yet implemented"); + php_error(E_WARNING, "module_name_drawtext: not yet implemented"); } /* }}} */ diff --git a/README.SUBMITTING_PATCH b/README.SUBMITTING_PATCH index 63b7156f100..57bd2881b87 100644 --- a/README.SUBMITTING_PATCH +++ b/README.SUBMITTING_PATCH @@ -50,6 +50,14 @@ Please make the mail subject prefix "[PATCH]". If attaching a patch, ensure it has a file extension of ".txt". This is because only MIME attachments of type 'text/*' are accepted. +Preferred way to propose PHP patch is sending pull request from github. + +https://github.com/php/php-src + +Fork official PHP repository and send pull request. It will be notified +to pull request mailing list. You can add pull requests to +http://bugs.php.net/ reports also. + PHP Documentation Patches ------------------------- From 76c098395df506692b1aba48ed0042cc1a27b491 Mon Sep 17 00:00:00 2001 From: Yasuo Ohgaki Date: Sun, 26 Jan 2014 18:30:25 +0900 Subject: [PATCH 2/4] Revert "Update source docs" This reverts commit 10d06cd4ff3038d2f02a18936793969e7aee0bda. --- CODING_STANDARDS | 25 +++---------------------- README.EXTENSIONS | 8 -------- README.EXT_SKEL | 30 ++++++------------------------ README.SUBMITTING_PATCH | 8 -------- 4 files changed, 9 insertions(+), 62 deletions(-) diff --git a/CODING_STANDARDS b/CODING_STANDARDS index fccc2b873db..7a0562e6ca9 100644 --- a/CODING_STANDARDS +++ b/CODING_STANDARDS @@ -82,7 +82,7 @@ Exceptions: library may need to control or free the memory, or when the memory in question needs to survive between multiple requests. -User Functions/Methods Naming Conventions +Naming Conventions ------------------ 1. Function names for user-level functions should be enclosed with in @@ -163,25 +163,6 @@ User Functions/Methods Naming Conventions 'foobar' 'foo_bar' -Internal Function Naming Convensions ----------------------- - -1. Exposed module API must be named 'php_modulename_function()' to avoid - symbol collision. They should be in lowercase, with words underscore - delimited. Exposed API must be defined in 'php_modulename.h'. - - PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS); - - Unexposed module function should be static and should not be defined in - 'php_modulename.h'. - - static int php_session_destroy(TSRMLS_D) - -2. Main module source file must be named 'modulename.c'. - -3. Header file that are used by other sources must be named 'php_modulename.h'. - - Syntax and indentation ---------------------- @@ -200,9 +181,9 @@ Syntax and indentation of PHP or one of its standard modules, please maintain the K&R style. This applies to just about everything, starting with indentation and comment styles and up to function declaration - syntax. Also see Indentstyle. + syntax. Also see Indentstyle_. - Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html +.. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html 3. Be generous with whitespace and braces. Keep one empty line between the variable declaration section and the statements in a block, as well as diff --git a/README.EXTENSIONS b/README.EXTENSIONS index e802af8329a..06d6cdd85f2 100644 --- a/README.EXTENSIONS +++ b/README.EXTENSIONS @@ -1,11 +1,3 @@ -This file describes extension module API details. Refer to -README.EXT_SKEL to create extension skeleton files. Refer to -Hacker's Guide for PHP internals. - -http://www.php.net/manual/en/internals2.php - - - Between PHP 4.0.6 and 4.1.0, the Zend module struct changed in a way that broke both source and binary compatibility. If you are maintaining a third party extension, here's how to update it: diff --git a/README.EXT_SKEL b/README.EXT_SKEL index 20b684ddfa6..d44fcc5c6a9 100644 --- a/README.EXT_SKEL +++ b/README.EXT_SKEL @@ -45,29 +45,12 @@ HOW TO USE IT --proto=filename. -SOURCE AND HEADER FILE NAME - - ./ext_skel generates 'module_name.c' and 'php_module_name.h' as main source - and header files. Keep these names. - - Module functions (User functions) must be named - - module_name_function() - - When you need to expose module functions to other modules, expose functions - strictly needed by others. Exposed internal function must be named - - php_module_name_function() - - See also CODING_STANDARDS. - - FORMAT OF FUNCTION DEFINITIONS FILE All the definitions must be on one line. In it's simplest form, it's just the function name, e.g. - module_name_function + my_function but then you'll be left with an almost empty function body without any argument handling. @@ -89,9 +72,8 @@ FORMAT OF FUNCTION DEFINITIONS FILE An example: - module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]]) + my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st - Arguments arg1 and arg2 is required. Arguments arg3 and arg4 are optional. If possible, the function definition should also contain it's return type @@ -151,15 +133,15 @@ EXAMPLE The following _one_ line - bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) + bool my_drawtext(resource image, string text, resource font, int x, int y [, int color]) will create this function definition for you (note that there are a few question marks to be replaced by you, and you must of course add your own value definitions too): -/* {{{ proto bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) +/* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y [, int color]) */ -PHP_FUNCTION(module_name_drawtext) +PHP_FUNCTION(my_drawtext) { char *text = NULL; int argc = ZEND_NUM_ARGS(); @@ -182,7 +164,7 @@ PHP_FUNCTION(module_name_drawtext) ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id); } - php_error(E_WARNING, "module_name_drawtext: not yet implemented"); + php_error(E_WARNING, "my_drawtext: not yet implemented"); } /* }}} */ diff --git a/README.SUBMITTING_PATCH b/README.SUBMITTING_PATCH index 57bd2881b87..63b7156f100 100644 --- a/README.SUBMITTING_PATCH +++ b/README.SUBMITTING_PATCH @@ -50,14 +50,6 @@ Please make the mail subject prefix "[PATCH]". If attaching a patch, ensure it has a file extension of ".txt". This is because only MIME attachments of type 'text/*' are accepted. -Preferred way to propose PHP patch is sending pull request from github. - -https://github.com/php/php-src - -Fork official PHP repository and send pull request. It will be notified -to pull request mailing list. You can add pull requests to -http://bugs.php.net/ reports also. - PHP Documentation Patches ------------------------- From f496aac1f6fc2b3ef30d5ed9539dbfdf9b4a1892 Mon Sep 17 00:00:00 2001 From: Yasuo Ohgaki Date: Sun, 26 Jan 2014 18:31:27 +0900 Subject: [PATCH 3/4] Update source docs --- CODING_STANDARDS | 25 ++++++++++++++++++++++--- README.EXTENSIONS | 8 ++++++++ README.EXT_SKEL | 30 ++++++++++++++++++++++++------ README.SUBMITTING_PATCH | 8 ++++++++ 4 files changed, 62 insertions(+), 9 deletions(-) diff --git a/CODING_STANDARDS b/CODING_STANDARDS index 7a0562e6ca9..fccc2b873db 100644 --- a/CODING_STANDARDS +++ b/CODING_STANDARDS @@ -82,7 +82,7 @@ Exceptions: library may need to control or free the memory, or when the memory in question needs to survive between multiple requests. -Naming Conventions +User Functions/Methods Naming Conventions ------------------ 1. Function names for user-level functions should be enclosed with in @@ -163,6 +163,25 @@ Naming Conventions 'foobar' 'foo_bar' +Internal Function Naming Convensions +---------------------- + +1. Exposed module API must be named 'php_modulename_function()' to avoid + symbol collision. They should be in lowercase, with words underscore + delimited. Exposed API must be defined in 'php_modulename.h'. + + PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS); + + Unexposed module function should be static and should not be defined in + 'php_modulename.h'. + + static int php_session_destroy(TSRMLS_D) + +2. Main module source file must be named 'modulename.c'. + +3. Header file that are used by other sources must be named 'php_modulename.h'. + + Syntax and indentation ---------------------- @@ -181,9 +200,9 @@ Syntax and indentation of PHP or one of its standard modules, please maintain the K&R style. This applies to just about everything, starting with indentation and comment styles and up to function declaration - syntax. Also see Indentstyle_. + syntax. Also see Indentstyle. -.. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html + Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html 3. Be generous with whitespace and braces. Keep one empty line between the variable declaration section and the statements in a block, as well as diff --git a/README.EXTENSIONS b/README.EXTENSIONS index 06d6cdd85f2..e802af8329a 100644 --- a/README.EXTENSIONS +++ b/README.EXTENSIONS @@ -1,3 +1,11 @@ +This file describes extension module API details. Refer to +README.EXT_SKEL to create extension skeleton files. Refer to +Hacker's Guide for PHP internals. + +http://www.php.net/manual/en/internals2.php + + + Between PHP 4.0.6 and 4.1.0, the Zend module struct changed in a way that broke both source and binary compatibility. If you are maintaining a third party extension, here's how to update it: diff --git a/README.EXT_SKEL b/README.EXT_SKEL index d44fcc5c6a9..20b684ddfa6 100644 --- a/README.EXT_SKEL +++ b/README.EXT_SKEL @@ -45,12 +45,29 @@ HOW TO USE IT --proto=filename. +SOURCE AND HEADER FILE NAME + + ./ext_skel generates 'module_name.c' and 'php_module_name.h' as main source + and header files. Keep these names. + + Module functions (User functions) must be named + + module_name_function() + + When you need to expose module functions to other modules, expose functions + strictly needed by others. Exposed internal function must be named + + php_module_name_function() + + See also CODING_STANDARDS. + + FORMAT OF FUNCTION DEFINITIONS FILE All the definitions must be on one line. In it's simplest form, it's just the function name, e.g. - my_function + module_name_function but then you'll be left with an almost empty function body without any argument handling. @@ -72,8 +89,9 @@ FORMAT OF FUNCTION DEFINITIONS FILE An example: - my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st + module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]]) + Arguments arg1 and arg2 is required. Arguments arg3 and arg4 are optional. If possible, the function definition should also contain it's return type @@ -133,15 +151,15 @@ EXAMPLE The following _one_ line - bool my_drawtext(resource image, string text, resource font, int x, int y [, int color]) + bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) will create this function definition for you (note that there are a few question marks to be replaced by you, and you must of course add your own value definitions too): -/* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y [, int color]) +/* {{{ proto bool module_name_drawtext(resource image, string text, resource font, int x, int y [, int color]) */ -PHP_FUNCTION(my_drawtext) +PHP_FUNCTION(module_name_drawtext) { char *text = NULL; int argc = ZEND_NUM_ARGS(); @@ -164,7 +182,7 @@ PHP_FUNCTION(my_drawtext) ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id); } - php_error(E_WARNING, "my_drawtext: not yet implemented"); + php_error(E_WARNING, "module_name_drawtext: not yet implemented"); } /* }}} */ diff --git a/README.SUBMITTING_PATCH b/README.SUBMITTING_PATCH index 63b7156f100..57bd2881b87 100644 --- a/README.SUBMITTING_PATCH +++ b/README.SUBMITTING_PATCH @@ -50,6 +50,14 @@ Please make the mail subject prefix "[PATCH]". If attaching a patch, ensure it has a file extension of ".txt". This is because only MIME attachments of type 'text/*' are accepted. +Preferred way to propose PHP patch is sending pull request from github. + +https://github.com/php/php-src + +Fork official PHP repository and send pull request. It will be notified +to pull request mailing list. You can add pull requests to +http://bugs.php.net/ reports also. + PHP Documentation Patches ------------------------- From d65ddb633d4fef54bd9715c4a159d8a7462eed2d Mon Sep 17 00:00:00 2001 From: Yasuo Ohgaki Date: Mon, 27 Jan 2014 06:50:11 +0900 Subject: [PATCH 4/4] Fix English and improve by Stas. Thanks :) --- CODING_STANDARDS | 9 +++++---- README.EXT_SKEL | 2 +- README.SUBMITTING_PATCH | 11 +++++++---- 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/CODING_STANDARDS b/CODING_STANDARDS index fccc2b873db..bebc951452b 100644 --- a/CODING_STANDARDS +++ b/CODING_STANDARDS @@ -166,9 +166,10 @@ User Functions/Methods Naming Conventions Internal Function Naming Convensions ---------------------- -1. Exposed module API must be named 'php_modulename_function()' to avoid - symbol collision. They should be in lowercase, with words underscore - delimited. Exposed API must be defined in 'php_modulename.h'. +1. Functions that are part of the external API should be named + 'php_modulename_function()' to avoid symbol collision. They should be in + lowercase, with words underscore delimited. Exposed API must be defined + in 'php_modulename.h'. PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS); @@ -179,7 +180,7 @@ Internal Function Naming Convensions 2. Main module source file must be named 'modulename.c'. -3. Header file that are used by other sources must be named 'php_modulename.h'. +3. Header file that is used by other sources must be named 'php_modulename.h'. Syntax and indentation diff --git a/README.EXT_SKEL b/README.EXT_SKEL index 20b684ddfa6..42df006d24b 100644 --- a/README.EXT_SKEL +++ b/README.EXT_SKEL @@ -91,7 +91,7 @@ FORMAT OF FUNCTION DEFINITIONS FILE module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]]) - Arguments arg1 and arg2 is required. + Arguments arg1 and arg2 are required. Arguments arg3 and arg4 are optional. If possible, the function definition should also contain it's return type diff --git a/README.SUBMITTING_PATCH b/README.SUBMITTING_PATCH index 57bd2881b87..ee8e6bbaefc 100644 --- a/README.SUBMITTING_PATCH +++ b/README.SUBMITTING_PATCH @@ -50,13 +50,16 @@ Please make the mail subject prefix "[PATCH]". If attaching a patch, ensure it has a file extension of ".txt". This is because only MIME attachments of type 'text/*' are accepted. -Preferred way to propose PHP patch is sending pull request from github. +The preferred way to propose PHP patch is sending pull request from +github. https://github.com/php/php-src -Fork official PHP repository and send pull request. It will be notified -to pull request mailing list. You can add pull requests to -http://bugs.php.net/ reports also. +Fork the official PHP repository and send a pull request. A +notification will be sent to the pull request mailing list. Sending a +note to PHP Internals list (internals@lists.php.net) may help getting +more feedback and quicker turnaround. You can also add pull requests +to bug reports at http://bugs.php.net/. PHP Documentation Patches