Ask Your Question
6

[Q&A] Documentation URL in answers ?

asked 2015-11-30 10:01:57 -0500

pklab gravatar image

I'm totally agree with @StevenPuttemans and others in OpenCV 3.0 doxygen documentation still very counter intuitive

In the mean time, which URL for the documentation we have to use while answering ?

Example for cv::circle

old doc url (very nice and persistent)

http://docs.opencv.org/modules/core/doc/drawing_functions.html#circle

automatically redirected to 2.4.11 version (redirection is nice too)

http://docs.opencv.org/2.4.11/modules/core/doc/drawing_functions.html#circle

link to current 3.0.0 Doxygen

http://docs.opencv.org/3.0.0/d6/d6e/group__imgproc__draw.html#gaf10604b069374903dbd0f0488cb43670

current 3.0.0 Sphinx

http://docs.opencv.org/3.0-last-rst/modules/imgproc/doc/drawing_functions.html#circle

Referring to the example:

  1. Which URL we have to use in answers ? I suppose current master but...
  2. Will anchors like #gaf10604b069374903dbd0f0488cb43670 survive in the future ?
  3. What about future of path /d6/d6e/group__imgproc__draw.html for Drawing Functions ?

In any case I would suggest better URL facing... is this possible with Doxygen ?

edit retag flag offensive close merge delete

Comments

1
  • The "current" 3.0.0 Sphinx is long outdated (Last updated on Dec 30, 2014), so I would avoid that.
  • If we want to unify things, I'd go with http://docs.opencv.org/2.4/... and http://docs.opencv.org/master/...as they're the most frequently updated (http://docs.opencv.org/3.0.0/ last update on Jun 3 2015)
  • Personally, I like to point to 2.4.x docs whenever possible for various reasons: 1) much intuitive docs, 2) references to Python functions, 3) same concerns as you about url persistence in 3.0 docs. I do however refer to 3.0.0 docs for tutorials, because I feel they are better structured (and obviously more updated)
LorenaGdL gravatar imageLorenaGdL ( 2015-11-30 10:37:23 -0500 )edit

Maybe we should have a wait and see how @mshabunin thinks about this? :)

StevenPuttemans gravatar imageStevenPuttemans ( 2015-12-01 03:03:25 -0500 )edit

1 answer

Sort by ยป oldest newest most voted
4

answered 2015-12-01 04:51:33 -0500

mshabunin gravatar image

updated 2015-12-01 04:55:10 -0500

Released documentation (/3.0.0, /2.4.11, etc.) will not be modified in future, thus you can safely refer to it. Nightly documentation (/master, /2.4) is not as stable and will change.

Similar scheme applies to GitHub links:

  • good link: https://github.com/Itseez/opencv/blob/3.0.0/CMakeLists.txt#L10
  • good link: https://github.com/Itseez/opencv/blob/7323823b/CMakeLists.txt#L10
  • bad link: https://github.com/Itseez/opencv/blob/master/CMakeLists.txt#L10 - master branch changes over time and this path or line number can become invalid

Old doc urls (docs.opencv.org/modules/...) should be avoided, because they can become obsolete in future. Redirection has been made to keep most of the old links working.

As I understand Doxygen anchors depend on full function signature (void cv::circle(InputOutputArray img, Point center, ... )) and paths depend on group/page identifier (imgproc_draw).

edit flag offensive delete link more

Comments

1

Thank you!

StevenPuttemans gravatar imageStevenPuttemans ( 2015-12-01 05:58:49 -0500 )edit
1

Well, I like 2.4 docs but I think is non sense to continue to use it in new answers.

So, despite of in my opinion doxygen urls are not friendly, we could unify things following @mshabunin scheme on 3.0.0 doc. Opinions ?

pklab gravatar imagepklab ( 2015-12-02 10:18:12 -0500 )edit
1

@pklab I would actually rather give people the latest possible link. 3.0.0 docs are way outdated. I rather have someone re-explaining or re-asking the correct link, then passing outdated information.

StevenPuttemans gravatar imageStevenPuttemans ( 2015-12-03 02:02:40 -0500 )edit
1

I agree with @StevenPuttemans. Stable releases are so sparse in time that docs become outdated pretty soon. Moreover, imagine the following situation: someone answers with a /3.0.0/ link to a function F today. Six months later, 3.1 version is already avaible and some other user reads the question. It is more likely that F function has suffered some standalone docs modification than the url path is no longer usable (because as Maksim said, it depends on the group, so I guess is unlikely for a function to change group). Also, this is a fact: if the URL doesn't work, the user will ask again with no doubt; if the URL is outdated, user won't notice it and he will probably miss new features or insights about function use/parameters

LorenaGdL gravatar imageLorenaGdL ( 2015-12-04 04:22:04 -0500 )edit
Login/Signup to Answer

Question Tools

2 followers

Stats

Asked: 2015-11-30 10:01:57 -0500

Seen: 189 times

Last updated: Dec 01 '15