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

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

Closed
tsteur opened this issue Oct 26, 2013 · 23 comments
Assignees
Labels
Enhancement For new feature suggestions that enhance Matomo's capabilities or add a new report, new API etc.
Milestone

Comments

@tsteur
Copy link
Member

tsteur commented Oct 26, 2013

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).
@tsteur
Copy link
Member Author

tsteur commented Oct 27, 2013

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

@mattab
Copy link
Member

mattab commented Nov 6, 2013

@mattab
Copy link
Member

mattab commented Nov 14, 2013

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

@tsteur
Copy link
Member Author

tsteur commented Nov 29, 2013

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).

@tsteur
Copy link
Member Author

tsteur commented Dec 2, 2013

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

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In a347ebc: refs #4244 converted more links

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

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

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

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

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

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

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In ee2936a: refs #4244 fix link

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In f0fa7f1: refs #4244 fix more links

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In 13a97ef: refs #4244 fix link

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In 9281714: refs #4244 fix link

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

@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"...

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In 0e756f1: refs #4244 fix some links

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In 7f147e1: refs #4244 fix some links

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In 790d17f: refs #4244 fix param

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

In b6c2cf9: refs #4244 fix param skip

@tsteur
Copy link
Member Author

tsteur commented Dec 3, 2013

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.

@tsteur
Copy link
Member Author

tsteur commented Dec 4, 2013

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.

@diosmosis
Copy link
Member

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.

@diosmosis
Copy link
Member

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

@mattab
Copy link
Member

mattab commented Dec 8, 2013

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

@tsteur tsteur 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
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
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
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
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

3 participants