March 29, 2012
H. S. Teoh wrote:
> and I start wondering where people bought their diplomas from...

Walmarts usually got the best deals.


March 29, 2012
On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller wrote:
> In another thread
> (http://forum.dlang.org/thread/CAMfGmZsNX3GsOFVyUaCX79E4H8eTBXqDmUJtm41JSzRNtME=RQ@mail.gmail.com)
> I raged about std.container's documentation, then Teoh pointed out
> that a lot of Phobos documentation needs improving. While he was
> talking about content, it got me thinking about the actual
> presentation of Phobos's documentation. Now, I have an interest in UX
> and I am a web developer my trade, so here's what I think it wrong
> with general layout+design right now and what could be done to fix it.
> -snip-

There is a simple project called cuteDoc (name comes from the old candyDoc theme) which has a demo using the Phobos documentation:

    http://robik.github.com/phobos/

Project home page:

    https://github.com/robik/cuteDoc

It has some rudimentary JavaScript for a module list and a generated jump-to table. I would love to see the Phobos documentation on dlang.org do something similar; there's so much low-hanging fruit for D's documentation that I wish someone with some web savvy would pick up on. It's pretty baffling to think that some Phobos modules have *manually maintained* table headers, what the heck were people thinking? What happened to automation?
March 29, 2012
On 29 March 2012 18:26, Jakob Ovrum <jakobovrum@gmail.com> wrote:
> There is a simple project called cuteDoc (name comes from the old candyDoc theme) which has a demo using the Phobos documentation:
>
>    http://robik.github.com/phobos/
>
> Project home page:
>
>    https://github.com/robik/cuteDoc

It looks ok, still a little too cluttered for my liking. Also, serif fonts on a web page...

> It has some rudimentary JavaScript for a module list and a generated jump-to table. I would love to see the Phobos documentation on dlang.org do something similar; there's so much low-hanging fruit for D's documentation that I wish someone with some web savvy would pick up on. It's pretty baffling to think that some Phobos modules have *manually maintained* table headers, what the heck were people thinking? What happened to automation?

I would, but I don't have the time. I've thought about it, but I work long days.

--
James Miller
March 29, 2012
On Thursday, 29 March 2012 at 05:41:30 UTC, James Miller wrote:
> On 29 March 2012 18:26, Jakob Ovrum <jakobovrum@gmail.com> wrote:
>> There is a simple project called cuteDoc (name comes from the old candyDoc
>> theme) which has a demo using the Phobos documentation:
>>
>>    http://robik.github.com/phobos/
>>
>> Project home page:
>>
>>    https://github.com/robik/cuteDoc
>
> It looks ok, still a little too cluttered for my liking. Also, serif
> fonts on a web page...

I think the theme has a long way to go. There are a lot of weird choices of colour and such, and I think it has too many boxes. I think it would look better if the style was toned down a little.

It's merely an example of how little effort is required to make DDoc better. Issues with DDoc itself aside, the current state of dlang.org is hardly representative of DDoc's full potential, when it should be striving to be just that.
March 29, 2012
On Thursday, 29 March 2012 at 01:52:28 UTC, James Miller wrote:
> On 29 March 2012 13:58, Nathan M. Swan <nathanmswan@gmail.com> wrote:
>> On Wednesday, 28 March 2012 at 22:43:19 UTC, foobar wrote:
>>>
>>> Categories - worst idea ever.
>>>
>>> What's better:
>>> int a; // this is size
>>> OR
>>> int size;
>>>
>>> Same thing applies here - code MUST be self documenting as much as
>>> possible.
>>
>>
>> But categories are still useful, e.g., when you want a function in
>> std.algorithm that looks for a specific element. It could be "search" or
>> "find" or "firstElemSatisfyingCondition", and even though those are all self
>> documenting, it would be a pain to look through the list of functions in
>> alphabetical order. The use of categories narrows your search for the
>> function down 20%.
>>
>> NMS
>
> Exactly my point. There is a line between "code must be self
> documenting" and "I need to read the code to understand what this
> does". Self documenting code is more about removing the cognitive
> stress of reading code. Actual documentation needs the whys and
> wherefores about everything.
>
> std.string is a brilliant example, with a list of 68 functions at the
> top, and a total of 89 anchors (presumably just overloads), there is
> no easy way to quickly find a function for a purpose. You have indexOf
> - a searching function - next to insert - a manipulation function -
> next to isNumeric - a property testing function. Each of those
> functions are "self-documenting" but that doesn't mean they wouldn't
> benefit from categorization.
>
> --
> James Miller

Have you considered that perhaps the granularity of Phobos modules is too coarse? Perhaps the core issue is too many functions are placed in one single file without more consideration of their relation and organization?

Regarding the documentation system itself - it should provide as much automation as possible. For instance, it should be able to group overloads together, it should be able to group kinds together - types, free functions, enums, etc. it should be able to group together various parts of a compound type (by protection, by kind: constructors, properties, operators, etc. )

Given the above *and* proper organization of code - which is *not* the case today - an *optional* tagging system could add some small benefit if it's automatic. E.g add a TAG macro.

Relying on documentation before exhausting the above is IMHO wrong.

As others said, the documentation and code comments should reflect what the code itself cannot express - what is the higher goal we want to achieve, which  specific implementation tradeoffs were taken and why, etc.

breaking algorithm.d into manually maintained documentation "categories" clearly misses the above points.
March 29, 2012
On Wednesday, 28 March 2012 at 23:30:32 UTC, Adam D. Ruppe wrote:
> On Wednesday, 28 March 2012 at 22:43:19 UTC, foobar wrote:
>> Categories - worst idea ever.
>
> I was just trying to copy what std.algorithm does,
> which is ok by me.
>
> Though, my implementation allows multiple categories;
> it is more of a tagging system (which is how my search
> program works too, it puts common alias in as tags).

As I said - I do appreciate your efforts :)
I just think the problem is deeper than just the documentation system though I do agree DDoc needs a lot more work.
I just feel that this specific issue is 98% about incorrect organization of code and only about 2% of improving DDoc presentation and usability.

At my previous work, the code base was so huge that the company's core library was designed to have a flat structure of files, eg component_file.cpp instead of component/file.cpp because someone decided this is the proper solution to reduce compilation times. apparently changing dirs increases compilation time.
This is butt ugly and vary inconvenient also given the moronic abbreviations used to shorten the file names.

I'm wondering at what point do we realize the problem is with the system and not us - clearly the long compilation times are due to C++ compilation model and not my organization of modules.
I can't influence the design of C++ but I hoped newer languages will learn from past mistakes. after all - should we serve the machine or should it serve us?
March 29, 2012
On 2012-03-29 11:24, foobar wrote:

> Have you considered that perhaps the granularity of Phobos modules is
> too coarse? Perhaps the core issue is too many functions are placed in
> one single file without more consideration of their relation and
> organization?
>
> Regarding the documentation system itself - it should provide as much
> automation as possible. For instance, it should be able to group
> overloads together, it should be able to group kinds together - types,
> free functions, enums, etc. it should be able to group together various
> parts of a compound type (by protection, by kind: constructors,
> properties, operators, etc. )
>
> Given the above *and* proper organization of code - which is *not* the
> case today - an *optional* tagging system could add some small benefit
> if it's automatic. E.g add a TAG macro.
>
> Relying on documentation before exhausting the above is IMHO wrong.
>
> As others said, the documentation and code comments should reflect what
> the code itself cannot express - what is the higher goal we want to
> achieve, which specific implementation tradeoffs were taken and why, etc.
>
> breaking algorithm.d into manually maintained documentation "categories"
> clearly misses the above points.

I completely agree.

-- 
/Jacob Carlborg
March 29, 2012
On 3/29/12 5:24 PM, foobar wrote:
> On Thursday, 29 March 2012 at 01:52:28 UTC, James Miller wrote:
>> On 29 March 2012 13:58, Nathan M. Swan <nathanmswan@gmail.com> wrote:
>>> On Wednesday, 28 March 2012 at 22:43:19 UTC, foobar wrote:

> Have you considered that perhaps the granularity of Phobos modules is
> too coarse? Perhaps the core issue is too many functions are placed in
> one single file without more consideration of their relation and
> organization?

I think it's just fine. Not everything is in std.algorithm, and that's good. Because everything we write is an algorithm, right?

I mean, what can I expect to find in std.algorithm? Binary search? Index of? Levenshtein distance? Spanning tree? Minimum weight? TSP?
March 30, 2012
Am Wed, 28 Mar 2012 18:40:17 +0200
schrieb "Nathan M. Swan" <nathanmswan@gmail.com>:

> That's pretty cool! I especially like the categories idea; it reminds me of Apple's documentation for Cocoa. It really helps you when you are thinking "I need a function which does...".
> 
> NMS

Unfortunately the function that reads a file in chunks is a _struct_ called (lower case) chunks.
The function that returns the current time is a method of the class Clock.
Categories help us to divide and conquer the documentation, but it can still be misleading at times. This is mostly due to the flexibility of the language, that allows to use structs as functions (opCall), classes as namespaces (static methods) as well as templates. On top of that there are concepts that are spread out over several modules. Especially string handling which is in both std.string and std.array. Other such cases can be found with std.range/std.algorithm, I/O and numerics.
Seriously, I think the way modules are complementing one another make it a bad approach in the long run to only document separate modules.

There have been a few attempts at making DDoc more digestible. My approach would be:

1. List use cases:
  * What's the parameter order of function X?
  * Give me an overview over [string manipulation|range algorithms|...].
  * What is contained in/the purpose of module X?
  * more?
2. Find out what is required to support each use case
  * Proposed concepts section?
  * Wiki pages/links
  * External DDoc files to allow documenting outside the constraints of a single module?
  * ...
3. Check back with what is already there and how to extend it

-- 
Marco

March 30, 2012
On 3/30/12, Marco Leise <Marco.Leise@gmx.de> wrote:
> snip

Here's another mind-bender:

import std.typetuple;
Tuple!(int, int) x;  // bzzzzz

It's in std.typecons of all places. I would assume a tuple would be in a module called typetuple, but no.
Next ›   Last »
1 2
Top | Discussion index | About this forum | D home