Polishing D - suggestions and comments

[Kris]

"Guillaume B." <guillaume.b.spam at sympatico.ca> wrote...
> Hi,
>
> I've started using Tango recently and I like most of it. What's really
> confusing for me is all the IO stuff: I'm never really sure of the
> relationship between Conduit, Stream, ... I thought about one thing that
> could help: in the API documentation, it would help a lot if there where
> more links. For example, in tango.sys.Process, Process.stdout returns a
> PipeConduit. But there is no link on PipeConduit that would bring me to 
> the
> page describing this class... So, I have to guess where it could be from
> the API index... Once I found that it's within tango.sys.Pipe, I see 
> "class
> PipeConduit : tango.io.DeviceConduit.DeviceConduit"... Again, there is no
> link so I have to return to the API index to find where DeviceConduit is
> defined (it's easy in this case)... With all this back and forward, it's
> hard to find what your looking for.

Yeah, this is frustrating, and a step backwards from when dOxygen was used 
in the past. Documentation production is currently based upon what the DMD 
compiler can produce, and unfortunately that does not generate cross-module 
references at this time.

We'd quietly hoped that someone in the community would write a cross-linking 
utility, to operate with DMD doc output, but it hasn't yet happened (that 
I'm aware of). Obviously, such a utility would benefit D as a whole.

But you're right ... something needs to be done about this. Perhaps Walter 
has some ideas about this also?


> It would also help if the API could be searched... The search on the site
> searches the whole wiki... And it doesn't seem really good: I know there
> must be a "trim" function somewhere but searching the wiki doesn't show
> that it's within tango.text.Util...


Try this page:  http://dsource.org/projects/tango/docs/current/

If you have your browser set to search as soon as you start typing, then it 
is surprisiing efficient to locate a module of interest. With FireFox I type 
a few letters and hit return. That gives me the doc generated via DMD and 
CandyDoc (with function links on the left), and if I want to see the current 
source code I can click on the big blue title at the top of the page. 
Perhaps the links from that page should open another tab, so the index page 
remains visible?


> Searching "site:http://dsource.org/projects/tango/docs/current/ trim" with
> Google does a much bether job... But the best would be an API search a
> little bit like http://www.gotapi.com/ : you type function names or 
> classes
> and it shows the result in real time...

That would be great, and we really should at least have a traditional 
cross-reference generated.


> So those where my suggestions...
>
> Guillaume

Thank you!