docproj.php Wiki
This PHP module provides HTML documentation using C-style comments.
Status: Alpha
Brought to you by:
ianl28
Menu
▾
▴
DOCPROJPHP V0.0.1G
This php module runs from the command line. Using preset headers inserted into the source code, it can be used to generate documentation for modules, methods and functions for any text-based source code, that uses C-style commenting such as PHP, C, C++, C#, JavaScript and Java. It is also able to include specified folders that are one level beneath the current folder, one level above, or in a sibling folder beneath the same parent folder.
1. Installation
1. Copy the one uncompressed file, docproj.php docproj_v<version>.php into the main folder of your PHP project.
2. Basic Usage and Default Settings
1. Enter cd <main-folder> to navigate via the command-line to the folder where the project source files are located.
2. Enter php docproj_v001g.php where '001g' is the current version i.e. 0.0.1G but without the dots and in lowercase, to run docprojphp.
3. Follow the instructions on the screen.
3. Command-line Options
DOCPROJPHP V0.0.1G UPDATED:2022-04-09
COMMAND-LINE OPTIONS:
Rules for Documenting Source Code
1. Documentation is inserted into the source code using 3 types of comments: 1) Modular/Class Comment, 2) Function/Method Comment, and 3) Section Comment.
2. All comment areas must have the whole line dedicated to the start of comment marker, i.e. /* and the end of comment marker, i.e. */. In other words any content that needs to be documented must be on the lines following the start of comment line, or preceding the end of the end of comment line.
3. The Modular/Class Comment contains information that applies to the entire source file. It must begin with a dedicated start-of-comment line with the forward slash, followed by asterisk, followed by space, and then a minimum of 7 equal signs, e.g. '/* ====='. It must end with a dedicated end-of-comment line with a minimum of 7 equal signs, followed by space, followed by asterisk, and then the forward slash, e.g. '======= */'.
4. The Function/Method Comment contains information that applies to the function or method that it precedes. It must begin with a dedicated start-of-comment line with the forward slash, followed by asterisk, followed by space, and then a minimum of 7 equal signs, e.g. '/* ====='. It must end with a dedicated end-of-comment line with a minimum of 7 minus signs, followed by space, followed by asterisk, and then the forward slash, e.g. '------- */'.
5. The Section Comment contains information that applies to the function or method that it precedes. It must begin with a dedicated start-of-comment line with the forward slash, followed by asterisk, followed by space, and then a minimum of 7 equal signs, e.g. '/* ====='. It must end with a dedicated end-of-comment line with a minimum of 7 dots, followed by space, followed by asterisk, and then the forward slash, e.g. '....... */'.
6. The Module/Class and Function/Method comment areas may include the following tags in uppercase followed by a colon: FILE, APPLICATION, VERSION, DESCRIPTION, LAST UPDATE, COPYRIGHT. The descriptions for these tags must be on the same single line and must not contain linefeeds or carriage returns onto additional lines.
7. The Section comment area may include the SECTION tag. This tag must be in uppercase followed immediately by a colon. The description after this tag with the be title of the section. The lines following this tag may be in free form text with linefeeds and carriage returns. HTML code may be used, and will be rendered as an HTML page in the documentation HTML file. In the section comment area, linebreaks are inserted automatically except where the line ends with an HTML tag, i.e. with the greater-than sign >. If a newline is required after this, then the HTML tag for linebreak <br/> must be inserted at the end of the line.
8. The README file for the project is automatically created when the docproj.php command is first run. It contains an example module comment area and section comment area. This file should contain the information that relates to the entire project.
9. The VERSION file for the project is automatically created when the docproj.php command is first run. This information is displayed under the VERSIONS page in the html documentation. All lines are ignored in this file except for the following:
Usage Tips
Change History
VERSION 0.0.1K 2022-05-??Gwellhiannau:
VERSION 0.0.1J 2022-05-??Gwellhiannau:
VERSION 0.0.1I 2022-05-??Gwellhiannau:
VERSION 0.0.1H 2022-05-??Gwellhiannau: Allansefiedig! Ychwanegu a dogfenniaethu dewisiad -l ar gyder iaith e.g. -lcy, hefyd angen i ddogfenniaethu sut i ychwanegu cod ar gyfer ieithoedd ereill. Allansefiedig! Ychwanegu a dogfenniaethu tagiau 'done', 'wip', 'curr', 'bug', 'urgent' a 'todo', ac hefyd yn y ffersiynau, pan mae'r llinell yn dechrau gyda | neu << a.a. Allansefiedig! Mae'r hawlfraint yn amwallu i hawlfraint cyflawn, sef pob hawlfraint wedi'u chadw, ond angen i gynnig dewisiadau i benodi e.e. -mit ar gyfer trwydded MIT, -ccbysa3 ar gyfer CC-BY-SA 3.0, -gpl4 ar gyfer GPL 4.0, a.a. gyda'r testun perthynasol yn eu gosodwyd lle maent nhw yn eu pherthynasol. Allansefiedig! dewisiad -a ar gyfer author, i benodi yr enw yr awdwr ar gyfer y neges neu hysbysiad hawlfraint. Mae'r hyn yn ei gadw gyda'r gosodiad -so (save options). Cyfredol! Dogfenniaeth: <<==1) 1. Angen i ddogfenniaethu modd newydd o mewnbynnu manylion ar gyfer yr hanes newidiadau, sef i ddechreu y llinell gyda'r '[0-9]. '.
Allansefiedig! gyda'r dewisiad -n gallu creu lluosogrwydd o ffeiliau ond mae'n angen i wneud hyn fel un air, h.y. heb unrhyw gwagle rhwng ac i mewn yr enw ffeiliau, gyda'r enw wedi'u gwahanwyd gyda'r atalnod. Allansefiedig! Yn y dewisiad -n, angen hefyd i gynnwys y peniad ar gyfer ffwythiant sydd ar y foment yn ei ddiffyg oherwydd mae'n cynwys torriadau modiwl a thoriad (neu adran) ond nid ffwythiant.
VERSION 0.0.1G 2022-04-09Gwellhiannau: Cwblhawyd! 220314a) Angen i ychwanegu y tagiau ar gyfer y lliwiau goleu hefyd ar gyfer y cynlluniau lliw sydd yn ysgafn, e.e. fel <yellow> a.a. Y lliwiau hyn ydy: gold, lightyellow, khaki, lemonchiffon, papayawhip, moccasin, peachpuff, yellow, lawngreen, chartreuse, lime, greenyellow, yellowgreen, springgreen, lightgreen, palegreen, lightcyan, cyan, aqua, aquamarine, paleturquoise, turquoise, powderblue, lightblue, skyblue, lightskyblue, deepskyblue, lavender, thistle, fuchsia, magenta, pink, lightpink, hotpink, deeppink, white, snow, honeydew, azure, seashell, beige. ivory, linen, mintcream, lightgray, silver, cornsilk, bisque, wheat, tan, sandybrown. Cwblhawyd! 220310b) Dewisiad -h ar gyfer help i allbynnu y manylion ar gyfer dewisiadau linell orchmynion ar y sgrin, ac yn uniongyrchol i ymadael yr swyddogaeth. Cwblhawyd! 220310a) dewisiadau -rm -rf -rs i osod peniadau i mewn i'r ffeil trwy'r e.e. yn defnyddio y gorchymyn vim r! php docproj_v001g.php -rm Cwblhawyd! 220309c) Dewisiad -n ar gyfer newydd - Creu ffeiliau newydd gyda'r peniadau, e.e. pan yn creu ffeil cod tarddiad e.e. .php, neu .cpp a.a., angen i greu ffeil gwag ond gyda'r peniadau eisoes yn eu gosodwyd i'w mewn. Cwblhawyd! 220309b) Angen i ychwanegu dewisiadau ar gyfer cynllum lliw, e.g. -col green, -col blue, -col darkgreen
VERSION 0.0.1F 2022-03-09Gwellhiannau: Cwblhawyd! 220309a) Pan yn rhedeg, angen i arddangos y gosodiadau ar gyfer y dewisiadau llinell-orchymyn, sef yr appfolders, appsuffixes a versiontop.
VERSION 0.0.1E 2022-03-08Bugfixes Cwblhawyd! 220308b) Settings file needs to be non-version specific so that when a new version is used, it is detected. When no ini file is present it needs to apply the default settings.
VERSION 0.0.1D 2022-03-08Gwellhiannau: New! Automatically save default settings Cwblhawyd! 220308a) create settings file everytime command-line options are specified so that they are saved each time from the previous run, enabling the last specified settings to serve as the default each time. Cwblhawyd! 220307a) New color tags for highlighting of text. New tags available for: 'blue red green darkorange firebrick orange coral purple maroon darkred sienna saddlebrown dimgray slategray darkslategray deeppink hotpink indigo darkmagenta darkorchid magenta darkslateblue slateblue midnightblue navy darkblue cornflowerblue dodgerblue deepskyblue olive darkolivegreen olivedrab seagreen darkgreen forestgreen limegreen tomato orangered crimson lightcoral salmon'. Cwblhawyd! 220307b) make default suffixes c,cpp,java,js,cs,php
VERSION 0.0.1B 2022-03-05 New! DocProjPHP help page New! Command-line options -s to specify suffixes, e.g. -s txt,sa1,sa2 -f to specify folders, e.g. -f subfolder1,subfolder2,..,../siblingfolder3
VERSION 0.0.1A 2022-02-28 New! Initial Release
Home
| Module | DOC.docproj.txt |
| Application | docproj.php |
| Version | 0.0.1G |
| Last Update | 2022-04-09 |
DOCPROJPHP V0.0.1G
This php module runs from the command line. Using preset headers inserted into the source code, it can be used to generate documentation for modules, methods and functions for any text-based source code, that uses C-style commenting such as PHP, C, C++, C#, JavaScript and Java. It is also able to include specified folders that are one level beneath the current folder, one level above, or in a sibling folder beneath the same parent folder.
1. Installation
1. Copy the one uncompressed file, docproj.php docproj_v<version>.php into the main folder of your PHP project.
2. Basic Usage and Default Settings
1. Enter cd <main-folder> to navigate via the command-line to the folder where the project source files are located.
2. Enter php docproj_v001g.php where '001g' is the current version i.e. 0.0.1G but without the dots and in lowercase, to run docprojphp.
3. Follow the instructions on the screen.
3. Command-line Options
DOCPROJPHP V0.0.1G UPDATED:2022-04-09
COMMAND-LINE OPTIONS:
| Option | Description |
|---|---|
| -f | Folder option - Use this option to document additional folders to the current folder specify the -f option followed by the single-word (no space) comma-delimited list of folders, e.g. the option -f subfolder1,../,../siblingfolder2 includes the subfolder subfolder1, the parent folder, and the sibling folder siblingfolder2 within the documentation path. |
| -s | Suffix option - Use this option to document alternate sourcode code with suffixes as an alternate to .php, .js, .cpp, .c, .cs, and .java, specify the -s option followed by the single-word (no space) comma-delimited list of suffixes (leaving out the dot), e.g. the option -s sa1,sa2,txt documents the files with suffixes .sa1, sa2, and .txt within the documentation path. |
| -vt | Versions top - Use this option to place the VERSIONS option at the top of the option list in the documentation index.html. This enables the Change History versions page to be displayed as the default first page. |
| -so | Save Options - Use this option to save the current command line options so that they are saved in the .ini file and are applied when no parameters are specified. To reset back to default options, one simply needs to delete the docprojphp.ini file. |
| -n | New file - Use this option to create a new source code file with the default documentation headers. |
| -col | Colour Scheme - Use this option to specify a colour scheme in the documentation HTML pages. The colour schemes currently available are green, darkgreen, blue, darkblue, maroon, darkmaroon, red, and darkred. |
| -rm | Vim read insert - Use this option to insert a module header template using the Vim command 'r! php docproj_v001g.php -rm <module-name>%%<module-description>'. Note that the double percentage signs are required as a delimiter. These fields should be entered without any spaces with the underscore instead of a space. |
| -rf | Vim read insert - Use this option to insert a module header template using the Vim command 'r! php docproj_v001g.php -rm <function-name<%%function-description>'. Note that the double percentage signs are required as a delimiter. These fields should be entered without any spaces with the underscore instead of a space. |
| -rs | Vim read insert - Use this option to insert a module header template using the Vim command 'r! php docproj_v001g.php -rm <section-title>%%<section-description>'. Note that the double percentage signs are required as a delimiter. These fields should be entered without any spaces with the underscore instead of a space. |
Rules for Documenting Source Code
1. Documentation is inserted into the source code using 3 types of comments: 1) Modular/Class Comment, 2) Function/Method Comment, and 3) Section Comment.
2. All comment areas must have the whole line dedicated to the start of comment marker, i.e. /* and the end of comment marker, i.e. */. In other words any content that needs to be documented must be on the lines following the start of comment line, or preceding the end of the end of comment line.
3. The Modular/Class Comment contains information that applies to the entire source file. It must begin with a dedicated start-of-comment line with the forward slash, followed by asterisk, followed by space, and then a minimum of 7 equal signs, e.g. '/* ====='. It must end with a dedicated end-of-comment line with a minimum of 7 equal signs, followed by space, followed by asterisk, and then the forward slash, e.g. '======= */'.
4. The Function/Method Comment contains information that applies to the function or method that it precedes. It must begin with a dedicated start-of-comment line with the forward slash, followed by asterisk, followed by space, and then a minimum of 7 equal signs, e.g. '/* ====='. It must end with a dedicated end-of-comment line with a minimum of 7 minus signs, followed by space, followed by asterisk, and then the forward slash, e.g. '------- */'.
5. The Section Comment contains information that applies to the function or method that it precedes. It must begin with a dedicated start-of-comment line with the forward slash, followed by asterisk, followed by space, and then a minimum of 7 equal signs, e.g. '/* ====='. It must end with a dedicated end-of-comment line with a minimum of 7 dots, followed by space, followed by asterisk, and then the forward slash, e.g. '....... */'.
6. The Module/Class and Function/Method comment areas may include the following tags in uppercase followed by a colon: FILE, APPLICATION, VERSION, DESCRIPTION, LAST UPDATE, COPYRIGHT. The descriptions for these tags must be on the same single line and must not contain linefeeds or carriage returns onto additional lines.
7. The Section comment area may include the SECTION tag. This tag must be in uppercase followed immediately by a colon. The description after this tag with the be title of the section. The lines following this tag may be in free form text with linefeeds and carriage returns. HTML code may be used, and will be rendered as an HTML page in the documentation HTML file. In the section comment area, linebreaks are inserted automatically except where the line ends with an HTML tag, i.e. with the greater-than sign >. If a newline is required after this, then the HTML tag for linebreak <br/> must be inserted at the end of the line.
8. The README file for the project is automatically created when the docproj.php command is first run. It contains an example module comment area and section comment area. This file should contain the information that relates to the entire project.
9. The VERSION file for the project is automatically created when the docproj.php command is first run. This information is displayed under the VERSIONS page in the html documentation. All lines are ignored in this file except for the following:
| start of line (ignore single-quotes) | Description |
|---|---|
| 'version ' | The version of the project should follow the word version followed by space, and then the date of the version, e.g. version 1.5.2a 25th April 2021. This line will act as the section or version header for the lines underneath it. |
| '* ' | Asterisk followed by space - this indicates a general functionality area. |
| '* !!' | Asterisk followed by space and then two exclamation marks - this indicates a new functionality area. |
| '#) ' | Hash followed by close bracket followed by space - this indicates an outsanding change that has not yet been completed. |
| '#!) ' | Hash followed by exclamation mark, followed by close bracket and space - this indicates a current change that is work in progress. |
| 'yymmdd?) ' | numerals representing the 2-digit year, month and day followed by an optional single letter followed by a closed bracket and space - this indicates a completed change. |
Usage Tips
- The templates.docprj is automatically created in the current directory if it does not exist. This contains the header templates for Module/Class, Function/Method and Section comment headers, that can be inserted into files for documentation.
- To document an HTML page, simply run the docproj.php command with the -s html option. This will add the .html suffix in addition to the default suffixes (c, cpp, cs, java, js, php). The Module/Class, Function/Method and Section comment sections can be inserted as normal, but they need to be included within the HTML comment section mark, i.e. <!-- at the start, and --> at the end. Note that these need to be inserted on separate lines before and after the comment start and end marker lines.
- If multiline formatting needs to be used for the single-line descriptions in the Module/Class and Function/Method comment header lines, HTML tags such as <br/> and <li> can be used. Note however that these need to be all on the same line as its tag (e.g. FILE:, APPLICATION:, LAST UPDATE:, etc). The same applies for the formatting in the version or change log file, VERSIONS.docproj.txt.
- The colors that have their own html tags for marking the tags in bold in the specified color e.g. <orange>This text is in orange bold</orange>, are as follows: <blue>blue</blue>, <red>red</red>, <green>green</green>, <darkorange>darkorange</darkorange>, <firebrick>firebrick</firebrick>, <orange>orange</orange>, <coral>coral</coral>, <purple>purple</purple>, <maroon>maroon</maroon>, <darkred>darkred</darkred>, <sienna>sienna</sienna>, <saddlebrown>saddlebrown</saddlebrown>, <dimgray>dimgray</dimgray>, <slategray>slategray</slategray>, <darkslategray>darkslategray</darkslategray>, <deeppink>deeppink</deeppink>, <hotpink>hotpink</hotpink>, <indigo>indigo</indigo>, <darkmagenta>darkmagenta</darkmagenta>, <darkorchid>darkorchid</darkorchid>, <magenta>magenta</magenta>, <darkslateblue>darkslateblue</darkslateblue>, <slateblue>slateblue</slateblue>, <midnightblue>midnightblue</midnightblue>, <navy>navy</navy>, <darkblue>darkblue</darkblue>, <cornflowerblue>cornflowerblue</cornflowerblue>, <dodgerblue>dodgerblue</dodgerblue>, <deepskyblue>deepskyblue</deepskyblue>, <olive>olive</olive>, <darkolivegreen>darkolivegreen</darkolivegreen>, <olivedrab>olivedrab</olivedrab>, <seagreen>seagreen</seagreen>, <darkgreen>darkgreen</darkgreen>, <forestgreen>forestgreen</forestgreen>, <limegreen>limegreen</limegreen>, <tomato>tomato</tomato>, <orangered>orangered</orangered>, <crimson>crimson</crimson>, <lightcoral>lightcoral</lightcoral>, <salmon>salmon</salmon>, <gold>gold</gold>, <lightyellow>lightyellow</lightyellow>, <khaki>khaki</khaki>, <lemonchiffon>lemonchiffon</lemonchiffon>, <papayawhip>papayawhip</papayawhip>, <moccasin>moccasin</moccasin>, <peachpuff>peachpuff</peachpuff>, <yellow>yellow</yellow>, <lawngreen>lawngreen</lawngreen>, <chartreuse>chartreuse</chartreuse>, <lime>lime</lime>, <greenyellow>greenyellow</greenyellow>, <yellowgreen>yellowgreen</yellowgreen>, <springgreen>springgreen</springgreen>, <lightgreen>lightgreen</lightgreen>, <palegreen>palegreen</palegreen>, <lightcyan>lightcyan</lightcyan>, <cyan>cyan</cyan>, <aqua>aqua</aqua>, <aquamarine>aquamarine</aquamarine>, <paleturquoise>paleturquoise</paleturquoise>, <turquoise>turquoise</turquoise>, <powderblue>powderblue</powderblue>, <lightblue>lightblue</lightblue>, <skyblue>skyblue</skyblue>, <lightskyblue>lightskyblue</lightskyblue>, <deepskyblue>deepskyblue</deepskyblue>, <lavender>lavender</lavender>, <thistle>thistle</thistle>, <fuchsia>fuchsia</fuchsia>, <magenta>magenta</magenta>, <pink>pink</pink>, <lightpink>lightpink</lightpink>, <hotpink>hotpink</hotpink>, <deeppink>deeppink</deeppink>, <white>white</white>, <snow>snow</snow>, <honeydew>honeydew</honeydew>, <azure>azure</azure>, <seashell>seashell</seashell>, <beige. ivory="">beige. ivory</beige.>, <linen>linen</linen>, <mintcream>mintcream</mintcream>, <lightgray>lightgray</lightgray>, <silver>silver</silver>, <cornsilk>cornsilk</cornsilk>, <bisque>bisque</bisque>, <wheat>wheat</wheat>, <tan>tan</tan>, <sandybrown>sandybrown</sandybrown>.
Change History
VERSION 0.0.1K 2022-05-??
VERSION 0.0.1J 2022-05-??
VERSION 0.0.1I 2022-05-??
VERSION 0.0.1H 2022-05-??
VERSION 0.0.1G 2022-04-09
VERSION 0.0.1F 2022-03-09
VERSION 0.0.1E 2022-03-08
VERSION 0.0.1D 2022-03-08
VERSION 0.0.1B 2022-03-05
VERSION 0.0.1A 2022-02-28
The wiki uses Markdown syntax.
Project Members:
- Ian Low (admin)