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 reply "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
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