Re: [Gretl-devel] Standards for function package help

On Wed, 22 Aug 2018, Sven Schreiber wrote: If you select a package in the function-package viewer window, right-click and choose Info (or click the Info button in the window's toolbar), gretl opens a window showing what it knows about the function: where it's located in the filesystem; its name, version and date; author's name and email; required gretl version; dataset requirement; and brief description -- this is all gleaned from the gfn metadata. Then the supplied help text is appended verbatim. In the case of packages that have PDF help, gretl prints the names of the public functions then a link to the PDF file. Related thought: a standard way of documenting individual functions in source code is via regimented comments -- the content of such comments can be extracted and pretty-printed by a suitable module, producing output such as https://developer.gnome.org/gtk2/2.24/GtkDialog.html It might be worth devising a suitable stuctured comment style for hansl functions. For example (just off the top of my head): function scalar foo (<args>) ## COMMENT ## Text goes here. ## More text if wanted. ## EXAMPLE ## open somedata ## y = foo(x) where "## COMMENT" (directly following the function signature) opens a block of lines starting with two hash marks, to be interpreted as commentary on the function's purpose, and "## EXAMPLE" starts a similar block showing an example call. In each case the special block is taken to end when we encounter a line that does not start with two hash marks. Line-breaks are often an issue, but in the ## COMMENT section we could employ the convention that lines are to be run into a single paragraph unless an empty line is inserted: ## COMMENT ## Para 1. ## Still para 1. ## ## Para 2. If this mechanism were combined with auto-generation of the function's signature from the gfn we could have a nicely set-out block of signature comments example for each public function. And in that case the actual "help text" in the gfn file could be confined to a general account of the purpose of the package, how it relates to the econometric literature and so on. That help text could use markdown, I guess. Allin