GNOME Bugzilla – Bug 752126
Add support for inline program documentation
Last modified: 2016-05-12 06:16:57 UTC
Create program documentation from documentation comments in source files.
Created attachment 307074 [details] [review] Add support for inline program documentation Create program documentation from documentation comments in source files.
Review of attachment 307074 [details] [review]: This patch supports various sections, including cmdsynopsis which is specific to program documentation. However, it is missing support for a separate options section and the new feature needs adding to the gtk-doc documentation.
Review of attachment 307074 [details] [review]: Can you attach a sample doc comment? ::: gtkdoc-scan.in @@ +271,3 @@ + if (m/\s\*\sPROGRAM\s*(.*)/) { + @TRACE@("Found PROGRAM comment in $input_file"); + if ($input_file =~ m/^.*[\/\\](.*)\.c+$/) { Hmm, can we also just create a <SECTION> entry here?
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #3) > Review of attachment 307074 [details] [review] [review]: > ::: gtkdoc-scan.in > @@ +271,3 @@ > + if (m/\s\*\sPROGRAM\s*(.*)/) { > + @TRACE@("Found PROGRAM comment in $input_file"); > + if ($input_file =~ m/^.*[\/\\](.*)\.c+$/) { > > Hmm, can we also just create a <SECTION> entry here? A <SECTION> entry require at least one symbol before output is created, which wouldn't be the case for a program. The <PROGRAM> section also identifies the section as a program and therefore OutputProgramDBFile() is used, which includes the program specific sections.
Created attachment 307164 [details] [review] Add support for inline program documentation Create program documentation from documentation comments in source files.
Review of attachment 307164 [details] [review]: This version skips the sections file altogether and outputs the program documentation directly from gtkdoc-mkdb.
Sample documentation comment: /** * PROGRAM:program-name * @short_description: short description of program * @synposis: program-name [OPTIONS] * * Long description of program. */
Two ideas: /** * PROGRAM:program-name * @short_description: short description of program * @synposis: program-name [OPTIONS] * @opt.help: display short help * @opt.version: show program version * @env.TOOL: if set do ... * * Long description of program. * * Returns: 0 for success and -1 in case of error */ If we don't want to do the special prefixed vars like "@opt." and "@env." another idea would be: /** * PROGRAM:program-name * @short_description: short description of program * @synposis: program-name [OPTIONS] * @opt.help: display short help * @opt.version: show program version * @env.TOOL: if set do ... * * Long description of program. * * Returns: 0 for success and -1 in case of error */ /** * program-name:options * @help: display short help * @version: show program version * * Free form option docs. */ /** * program-name:environment * @TOOL: if set do ... * * Free form env docs. */ Still weird, right? Another option would be markdown for the whole block.
Created attachment 307401 [details] [review] mkdb: add support for exit status in program documentation Add exit status section by using the "Returns:" documentation.
Created attachment 307402 [details] [review] mkdb: add support for the options section Options can be listed as parameters in the PROGRAM section by prefixing the option with "opt." Parameters in square brackets are converted to replaceable entries. This implementation doesn't automatically add a '-' or '--' prefix to options, so these need to be included in the option name. The options also cannot contain spaces, so any arguments to options need to include an equals symbol. There is also no support for more than one option with the same description (e.g. "-h, --help"). /** * PROGRAM:program-name * @synopsis: program-name [OPTIONS...] * @opt.--file=[FILENAME]: specify a file * @opt.--help: display short help */
Created attachment 307403 [details] [review] mkdb: parse command synopsis for parameters Create command and arg tags for the cmdsynopsis section. The first item is the command name and any subsequent items are parameters. If a parameter is enclosed in square brackets it is marked as optional and curly brackets indicate the parameter is required. Parameters ending in "..." are repeatable and if the parameter is upper case, it is replaceable. /** * PROGRAM:program-name * @synopsis: program-name [OPTIONS...] --module=MODULE_NAME {FILE} */
Created attachment 307568 [details] [review] Add support for inline program documentation This patch combines the previous patches and makes the following changes: * Use *italic* markdown formatting for replaceable elements. This matches the man page convention of using italics to indicate replaceable arguments. * Add default synopsis section using the program name. * Make the Options section optional. * Split options based on commas to support multiple options with a single description (e.g. "-h, --help: display help text"). * Don't require "opt." prefix for command options, instead require command line options to start with '-'. * Allow spaces in parameter names to allow "--arg value" instead of "--arg=value". * Parse markdown in the Exit Status section. * Remove @title override support as the title should always be the program name.
Created attachment 313759 [details] [review] Add support for inline program documentation This version of the patch adds a test for program documentation and also fixes parameter matching with spaces by using non-greedy matching.
The following fix has been pushed: a9864c4 Add support for inline program documentation
Created attachment 324626 [details] [review] Add support for inline program documentation Create program documentation from documentation comments in source files.
Sorry for the long delay in reviews. Could you also please send a patch for the docs as a followup.
Hello, Thanks for the update. Sure do. Should I use the ml for that?
Marius, the docs are in docbook here: https://git.gnome.org/browse/gtk-doc/tree/help/manual/C/index.docbook You could add a section after this one: https://developer.gnome.org/gtk-doc-manual/unstable/documenting_symbols.html.en
Ping, I would need this for the next release.
Haven't forgotten, just a little caught up w/ other stuff. Will try to do it this week.
Created attachment 327300 [details] [review] Documentation Added a patch for documentation. First attempt, let me know if this complies.
Review of attachment 327300 [details] [review]: Thanks ::: help/manual/C/index.docbook @@ +1412,3 @@ </sect1> + <sect1 id="documenting_inline_program"> Please fix the indentation. @@ +1415,3 @@ + <title>Inline program documentation</title> + <para> + You can document programs using inline documentation. You can document programs and their commandline interface using inline documentation.
Created attachment 327356 [details] [review] Documentation (revised) Uploaded a revised version.
The following fix has been pushed: dc31758 help/manual/C: Added documentation for inline program documentation.
Created attachment 327675 [details] [review] help/manual/C: Added documentation for inline program documentation. v2: Fixed indentation and description (Stefan Sauer) Signed-off-by: Marius Vlad <marius.c.vlad@intel.com>