Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

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

Closed
mattab opened this Issue · 7 comments

2 participants

@mattab
Owner

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
Owner

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

@tsteur
Owner

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

@tsteur
Owner

In b061d3a: refs #4194 ignore console commands

@tsteur
Owner

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

@tsteur
Owner

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

@tsteur
Owner

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
@tsteur tsteur was assigned by mattab
@sabl0r sabl0r referenced this issue from a commit in sabl0r/piwik
@tsteur tsteur refs #4194 ignore console commands b061d3a
@sabl0r sabl0r referenced this issue from a commit in sabl0r/piwik
@tsteur tsteur refs #4194 the api ignore tag is not needed, we simply ignore all sym…
…fony commands in the api generator
6aa7ab6
@sabl0r sabl0r referenced this issue from a commit in sabl0r/piwik
@tsteur tsteur refs #4194 marked some more classes as api 461df89
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.