www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - ddoc should generate hyperlinks to source code

reply "timotheecour" <timothee.cour2 gmail.com> writes:
enhancement request:
in the ddoc documentation generation, hyperlinks should appear:

bool equal(Range1, Range2)(Range1 r1, Range2 r2);
=> should contain a hyperlink from 'equal' to source code 
defining that function.
The hyperlink target should be customizable, either a url (eg: 
github, making sure it's retrieving the proper commit id so that 
code is in sync with ddoc), or local file system for users.

more complex example:
SortedRange!(Range, less) sort(alias less = "a < b", SwapStrategy 
ss = SwapStrategy.unstable, Range)(Range r);

here hyperlinks should appear on template SortedRange, enum 
SwapStrategy, and the correct overload of sort.

Thanks for any feedback!
Mar 12 2013
next sibling parent "bearophile" <bearophileHUGS lycos.com> writes:
timotheecour:

 enhancement request:
 in the ddoc documentation generation, hyperlinks should appear:

 bool equal(Range1, Range2)(Range1 r1, Range2 r2);
 => should contain a hyperlink from 'equal' to source code 
 defining that function.

I am suggesting the same idea since some time :-) You see this idea used in normal Haskell documentation, where functions have links on the right to their source code: http://www.haskell.org/ghc/docs/latest/html/libraries/base/Prelude.html It's handy because in tricky situations the source helps you understand the full exact semantic of the function. The link avoids you wasting time searching the function in a long module source code. Bye, bearophile
Mar 12 2013
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 3/12/2013 8:47 PM, timotheecour wrote:
 enhancement request:
 in the ddoc documentation generation, hyperlinks should appear:

 bool equal(Range1, Range2)(Range1 r1, Range2 r2);
 => should contain a hyperlink from 'equal' to source code defining that
function.
 The hyperlink target should be customizable, either a url (eg: github, making
 sure it's retrieving the proper commit id so that code is in sync with ddoc),
or
 local file system for users.

 more complex example:
 SortedRange!(Range, less) sort(alias less = "a < b", SwapStrategy ss =
 SwapStrategy.unstable, Range)(Range r);

 here hyperlinks should appear on template SortedRange, enum SwapStrategy, and
 the correct overload of sort.

 Thanks for any feedback!

It's a good idea.
Mar 12 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Wednesday, 13 March 2013 at 03:47:10 UTC, timotheecour wrote:
 The hyperlink target should be customizable, either a url (eg: 
 github, making sure it's retrieving the proper commit id so 
 that code is in sync with ddoc), or local file system for users.

In order to link to the local file system, the distribution needs to contain HTML-rendered source code. There is no convention for linking to a specific place in a text file. I think including .html versions of all Phobos source code is not worth it for the links alone. However, it would be nice if there was a HTML version of the source code, which contained links to each identifier's definitions wherever they appear, such as the LXR project: See e.g. http://lxr.linux.no/#linux+v3.8.2/kernel/acct.c For for GitHub links, the makefile could create a .ddoc inclusion file which defines the URL base (pointing to GitHub, to the current commit), for the compiler to use when generating the links in the documentation.
Mar 12 2013
prev sibling next sibling parent "timotheecour" <timothee.cour2 gmail.com> writes:
when I click on source next to abs, it goes to 
"http://www.haskell.org/ghc/docs/latest/html/libraries/base/src/GHC-Num.html#abs"
which is not a very precise location, and it's not clear the doc 
is in sync with code shown


 In order to link to the local file system, the distribution 
 needs to contain HTML-rendered source code.

how about this: in the doc: (http://dlang.org/phobos/std_path.html) pure trusted inout(C)[] baseName(C)(inout(C)[] path); baseName will be hyperlinked to: https://github.com/D-Programming-Language/phobos/blob/2.062/std/path.d#L274 which points exactly to write place in source code (no need for custom '#abs'-like tag as in haskell docs above), AND guarantees docs in sync with source (since we have correct tag in github). The line info can be obtained in ddoc generation tool. A command line flag to dmd would specify the base (github url or ddoc generated html files on user's file system). The makefile would in turn call that dmd flag.
 I think including .html versions of all Phobos source code is 
 not worth it for the links alone.

not necessary, thanks to github already giving us this for free, see above.
 such as the LXR project: See e.g. 
 http://lxr.linux.no/#linux+v3.8.2/kernel/acct.c

sure, but starting at least with all function names and defined types should be a first priority; those can be obtained from json.
Mar 13 2013
prev sibling parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 13.03.2013 04:47, schrieb timotheecour:
 enhancement request:
 in the ddoc documentation generation, hyperlinks should appear:
 
 bool equal(Range1, Range2)(Range1 r1, Range2 r2);
 => should contain a hyperlink from 'equal' to source code defining that
 function.
 The hyperlink target should be customizable, either a url (eg: github,
 making sure it's retrieving the proper commit id so that code is in sync
 with ddoc), or local file system for users.
 
 more complex example:
 SortedRange!(Range, less) sort(alias less = "a < b", SwapStrategy ss =
 SwapStrategy.unstable, Range)(Range r);
 
 here hyperlinks should appear on template SortedRange, enum
 SwapStrategy, and the correct overload of sort.
 
 Thanks for any feedback!

In the ddox based documentation that there is a source code link at the top of each item's page: http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/equal.html Types are generally cross-linked within the documentation instead of directly linking to the source code, though.
Mar 13 2013