Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automatically generate PHP Source code documentation for developers (classes, methods) #4194

Closed
mattab opened this issue Oct 4, 2013 · 7 comments
Assignees
Labels
Critical Indicates the severity of an issue is very critical and the issue has a very high priority. Enhancement For new feature suggestions that enhance Matomo's capabilities or add a new report, new API etc.
Milestone

Comments

@mattab
Copy link
Member

mattab commented Oct 4, 2013

Piwik core contains a significant amount of classes. Many of these are used in several places in core and plugins and will be used by plugin developers.

The goal of this ticket is to provide Piwik Plugin developers with a great documentation about the classes and methods which are most useful to them when making plugins.

This ticket focus is on deciding which parts of the code (classes, methods) are useful to other developers.

  • typical classes that will be used by devs include Url, UrlHelper, DataTable, Date, Db, Http, Ip, Log, ...
  • Maybe we use a custom phpdoc annotation, which could be picked up by phpdoc to autogenerate our public API documentation. eg. @framework or @platform or @UseIT ....
  • annotation could be set on the class (in which case all public methods' docs would be generated), or the tag could be set on specific methods (in case other public methods would not really useful to plugin devs) <- limits noise & need to write docs
  • docs ideally would be generated in markdown so we could integrate within marketplace and/or piwik.org website easily (if this can be done with phpdoc)
  • automated on Travis CI when the build was green (alternatively we put a cron on piwik.org)

At the end we should have auto generated doc which developers can easily use when they need something already implemented in Piwik.

@tsteur
Copy link
Member

tsteur commented Oct 5, 2013

The @api seems to be appropriate: http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/api.html

@tsteur
Copy link
Member

tsteur commented Oct 7, 2013

In c94adb6: refs #4194 marked some classes and methods as API to test doc generation

@tsteur
Copy link
Member

tsteur commented Oct 7, 2013

In 29c57ee: refs #4194 marked some classes/methods/functions as available for plugins

@tsteur
Copy link
Member

tsteur commented Oct 7, 2013

In b061d3a: refs #4194 ignore console commands

@tsteur
Copy link
Member

tsteur commented Oct 7, 2013

In 6aa7ab6: refs #4194 the api ignore tag is not needed, we simply ignore all symfony commands in the api generator

@tsteur
Copy link
Member

tsteur commented Oct 7, 2013

In 461df89: refs #4194 marked some more classes as api

@tsteur
Copy link
Member

tsteur commented Oct 7, 2013

Closing this now. Documentation generator is located here: https://github.com/piwik/pluginapi-doc-generator/

Follow up tickets created: #4200 #4201

@mattab mattab added this to the 2.0 - Piwik 2.0 milestone Jul 8, 2014
sabl0r pushed a commit to sabl0r/piwik that referenced this issue Sep 23, 2014
sabl0r pushed a commit to sabl0r/piwik that referenced this issue Sep 23, 2014
sabl0r pushed a commit to sabl0r/piwik that referenced this issue Sep 23, 2014
sabl0r pushed a commit to sabl0r/piwik that referenced this issue Sep 23, 2014
…re all symfony commands in the api generator
sabl0r pushed a commit to sabl0r/piwik that referenced this issue Sep 23, 2014
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Critical Indicates the severity of an issue is very critical and the issue has a very high priority. Enhancement For new feature suggestions that enhance Matomo's capabilities or add a new report, new API etc.
Projects
None yet
Development

No branches or pull requests

2 participants