Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Hook documentation generator - add links to classes and methods in the developer guides and auto generated docs #4244

Closed
tsteur opened this Issue · 23 comments

3 participants

Thomas Steur Matthieu Aubry Benaka
Thomas Steur
Owner

The goal of this ticket is to make all links in pages and guides of developer.piwik.org work and link to the correct resources.

Features

  • Provide a way to link to classes and methods
  • Provide a way to link to hooks
  • Link to a custom URL
  • update existing links in comments (or missing links)

QA

  • all existing comments of Piwik should be converted and the links on developer.piwik.org should all work (in hooks and classes docs).
Thomas Steur
Owner

FYI:
Link from hooks to classes/methods is doable in approx one day or less.

Links from classes/methods to hooks: multiple days for #4242 + half a day or so for this feature

Matthieu Aubry
Owner

IMHO this is the last key missing feature of developer.piwik.org

Thomas Steur
Owner

For links in PHPDoc I am thinking about supporting the following type of inline links:

 * {@link Map}  // class within this namespace
 * {@link Piwik\DataTable\Map}  // full classname
 * {@link getKeyName()}   // method within this class
 * {@link $myproperty}    // property within this class
 * {@link Map::getKeyName()} // method from any class
 * {@link Map::$myproperty}  // property from any class
 * {@link http://piwik.org}  // http link
 * {@link https://piwik.org} // https link
 * {@link mailto:test}       // mailto link
 * {@link link description}  // description which will be displayed instead of the acutal link

If the link to the class or method or whatever is public and has API tag, I will replace the link with an actual link. If not, I will probably only mark the name of the class, property, ... as "code" (wrap it in backticks).

Thomas Steur
Owner

In fcf22b6: refs #4244 updated some existing links to use link inline tag

Thomas Steur
Owner

In a347ebc: refs #4244 converted more links

Thomas Steur
Owner

In 55442e6: refs #4244 fix complete comment is a link

Thomas Steur
Owner

In 331bb0e: refs #4244 escape the underscore, will be emphasized otherwise

Thomas Steur
Owner

In 7672be7: refs #4244 replaced some links to hooks.

Thomas Steur
Owner

In ee2936a: refs #4244 fix link

Thomas Steur
Owner

In f0fa7f1: refs #4244 fix more links

Thomas Steur
Owner

In 13a97ef: refs #4244 fix link

Thomas Steur
Owner

In 9281714: refs #4244 fix link

Thomas Steur
Owner

@diosmosis

currently supported is https://github.com/piwik/developer-documentation/blob/master/README.md#supported-inline-tags-in-comments . Can you think of more? Is anything else needed?

There are still some (5-10) "broken/missing" links to some guides. I don't want to set them yet as the links might change... Can you fix the links? Just search for "(#)" or "](#".

"and the links should all work"... the "should" work. Tested with some broken links checker and clicked manually through some pages but hard to say they all work for sure!

Open:

  • Tests if possible
  • Output list of not resolved links / undocumented hooks somewhere. A link can be unresolved because for instance the target has not an "@api" tag or the method / property is not "api"...
Thomas Steur
Owner

In 0e756f1: refs #4244 fix some links

Thomas Steur
Owner

In 7f147e1: refs #4244 fix some links

Thomas Steur
Owner

In 790d17f: refs #4244 fix param

Thomas Steur
Owner

In b6c2cf9: refs #4244 fix param skip

Thomas Steur
Owner

I am now logging to STDOUT which links are not resolved. A summary is available here: http://pastebin.com/Bj1jDEkQ

The links are not resolved if the target class is not API or if there are links to protected methods which are not marked as API. Basically all Constants were not resolved as well (not in the list) as we can only link to constants having a long description (Constants having no long description are not displayed on developer.piwik.org). In this case we just highlight the constant as code but do not link to it.

Thomas Steur
Owner

BTW: Because I've seen a link to a twig function: It is still to be defined how to document Twig filters and JavaScript functions. Not really related to this ticket but noticed it during working on this.

Benaka
Collaborator

Found a bug/limitation in Sami that needs to be fixed: block elements in @param & related tags do not show up correctly. For example:

@param array $abc A B C

                  - A
                  - B

appears as

$abc (array) A B C - A - B

I've looked into the fix, and it seems to involve three things:

  1. DocBlockParser::normalizeString($str) should be changed to return preg_replace('/\h\n\h/', "\n", trim($str));
  2. In macros.twig and other places, text should be moved to a new paragraph after markdown in text is indented properly. So something like:
- {{ paramName }} ({{ paramTypeHints }})

    {{ paramDescription|indentNewLines }}

Where indentNewLines indents each newline by however many spaces so it becomes part of the description element.

  1. Style the new paragraph so it appears in the right place.

Not sure how to do step 2, so can't fix it myself.

Benaka
Collaborator

Nevermind, fixed it. Had to fork tsteur/Sami, btw. Fork is located at piwik/Sami on github.

Matthieu Aubry
Owner

Fantastic work guys... @capedfuzz what is the status of this ticket, can you close the ticket?

Thomas Steur tsteur added this to the 2.0 - Piwik 2.0 milestone
Benaka diosmosis was assigned by tsteur
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 converted more links a347ebc
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix complete comment is a link 55442e6
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 replaced some links to hooks. 7672be7
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix link ee2936a
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix more links f0fa7f1
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix link 13a97ef
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix link 9281714
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix some links 0e756f1
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix some links 7f147e1
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix param 790d17f
Philip Taffner sabl0r referenced this issue from a commit in sabl0r/piwik
Thomas Steur tsteur refs #4244 fix param [ci skip] b6c2cf9
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.