Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

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

Closed
mattab opened this Issue · 7 comments

2 participants

Matthieu Aubry Thomas Steur
Matthieu Aubry
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.

Thomas Steur
Owner

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

Thomas Steur
Owner

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

Thomas Steur
Owner

In b061d3a: refs #4194 ignore console commands

Thomas Steur
Owner

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

Thomas Steur
Owner

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

Thomas Steur
Owner

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

Follow up tickets created: #4200 #4201

Matthieu Aubry mattab added this to the 2.0 - Piwik 2.0 milestone
Thomas Steur tsteur was assigned by mattab
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4194 ignore console commands b061d3a
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4194 the api ignore tag is not needed, we simply ignore all sym…
…fony commands in the api generator
6aa7ab6
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur 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.