Subject: Documented Source shows gaps ?

Posted on: 04/01/2014 07:02am
By: remy

I wonder why some functions are ignored by phpDocumenter.
One example: COM_createHTMLDocument

Than, I would like to read about the document that is created. Besides references to the api, there seems to be no screenshots ? What about wireFrames?

Than, when a text refers to 'the api', what does that mean? Is a link possible?

Re: Documented Source shows gaps ?

Posted on: 04/01/2014 07:54am
By: Dirk

Hmm, seems that phpDocumentor was running on a repository that was horribly out of date. And now that I've updated it, it stops creating the documentation halfway through.

Have to look into this. Thanks for bringing this to our attention!

bye, Dirk

Re: Documented Source shows gaps ?

Posted on: 05/01/2014 04:36am
By: Dirk

Should be up to date now: http://project.geeklog.net/src/

I should move this process to Jenkins so that failures become more visible.

bye, Dirk

Re: Documented Source shows gaps ?

Posted on: 05/01/2014 04:42am
By: Dirk

Quote by: remy

Than, I would like to read about the document that is created. Besides references to the api, there seems to be no screenshots ? What about wireFrames?


This is created by running phpDocumentator over the Geeklog source code. All we can do is give the tool some hints with special tags, like @return etc. There are no screenshots for this process, obviously.

Not sure what you mean by wireframes.


Quote by: remy

Than, when a text refers to 'the api', what does that mean? Is a link possible?


Depends on the context you're referring to. There's the Plugin API. Or it could simply mean API in the general sense of "the interface of a function or class".

bye, Dirk

Re: Documented Source shows gaps ?

Posted on: 05/01/2014 05:27am
By: remy

The phpDocumentor output looks more complete now, thanks.

All we can do is give the tool some hints with special tags, like @return etc.

This is what the listing says about the parameter $information for COM_createHTMLDocument:

PHP Formatted Code
An array defining variables to be used when creating the output string 'what' If 'none' then no left blocks are returned, if 'menu' (default) then right blocks are returned string 'pagetitle' Optional content for the page's <title> string 'breadcrumbs' Optional content for the page's breadcrumb string 'headercode' Optional code to go into the page's <head> boolean 'rightblock' Whether or not to show blocks on right hand side default is no (-1) array 'custom' An array defining custom function to be used to format Rightblocks

I do have troubles to understand these hints. Though, updating my plugin(s) to follow the trends requires some understanding. Same goes for other functions like ADMIN_list. The lack of examples or links (like: see the wiki at ...) makes the update a daunting task which is easily postponed.

A wireframe could be used to show the structure of the display, possibly mentioning the id's or class of the div's generated. Well, for complex functions it would be very useful.

There's the Plugin API.

This API is a manifest for 'mandatory' plugin components. It's a description of the API that a plugin should expose to the portal.
When I read in the documentation 'the api' would it be the case that the wiki page 'plugin API' is referenced?

Geeklog - Forum
https://www.geeklog.net/forum/viewtopic.php?showtopic=95495