Re: New documentation layout
On Monday, 31 March 2014 at 08:43:14 UTC, Colin Grogan wrote: I made a comment under it, but there seems to be no traffic there. It's still sort of pre-release (and I still feel quite strongly that the embedded comment system is a bad idea in the first place). Is there a thread elsewhere that would be more suitable for this? A few quick google searches didnt show anything up. This would be the most recent discussion, I think: http://forum.dlang.org/post/lfjcfm$2frn$1...@digitalmars.com -Wyatt
New documentation layout
Not sure where to discuss this, but what are peoples thoughts on the new layout for the phobos documentation? Link - http://dlang.org/library/index.html I made a comment under it, but there seems to be no traffic there. Is there a thread elsewhere that would be more suitable for this? A few quick google searches didnt show anything up. My thoughts on the new layout: (copy and pasted to save typing!!) I'm liking the new layout, its good to seperate out classes,methods etc for each module at the top of the page, giving a simple overview of the module you can see at a glance. However, one gripe, having the info on each class/method/enum etc in a module on its own separate page is a little cumbersome. I think having everything that is in a module on one page makes it easier to find things, as you can use ctrl+f or whatever. Having to go back and forth between the module and its classes is a bit of a distraction no? Also, how close to being final is this preview?
Re: Documentation Layout
Am Wed, 28 Mar 2012 18:40:17 +0200 schrieb Nathan M. Swan nathanms...@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
Re: Documentation Layout
On 3/30/12, Marco Leise marco.le...@gmx.de wrote: snip Here's another mind-bender: import std.typetuple; Tuple!(int, int) x; // bz It's in std.typecons of all places. I would assume a tuple would be in a module called typetuple, but no.
Re: Documentation Layout
On Thursday, 29 March 2012 at 05:41:30 UTC, James Miller wrote: On 29 March 2012 18:26, Jakob Ovrum jakobov...@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.
Re: Documentation Layout
On Thursday, 29 March 2012 at 01:52:28 UTC, James Miller wrote: On 29 March 2012 13:58, Nathan M. Swan nathanms...@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.
Re: Documentation Layout
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?
Re: Documentation Layout
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
Re: Documentation Layout
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 nathanms...@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?
Documentation Layout
In another thread (http://forum.dlang.org/thread/CAMfGmZsNX3GsOFVyUaCX79E4H8eTBXqDmUJtm41JSzRNtME=r...@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. 1. The Jump To index. This is the worst one for me, hence top of the list, its an inline list of the classes, structs and functions on the page. Actually, technically its a list of all the anchors on the page, with duplicate names removed and then sorted (poorly) and outputted all in a row. While this is manageable for say std.array, its ~4.5 lines on std.string. Some modules have tables at the beginning that replace the index, and this is better (std.algorithm for example) but can become out of date, due to the fact that it is hand-maintained. 2. No ordering + unobvious separation of elements Due to what I can only assume is the way DDoc generates code, there is no obvious ordering to the page, you can have a class definition followed by its methods followed by a few top-level functions then a struct and its members. Combine this with the fact that all things are styled the same, with indenting for members, you can easily get lost scanning through a class when you suddenly find yourself at a completely different class. 3. No search Ok, there is a search, it is a small box, near the top, that searches either: the entire site, the library reference or the news group. It hands it off to Google and returns a Google search. This isn't very good for user experience, ideally you wouldn't leave the site, it would be internal and use the fact that you are searching documentation to be a bit smarter about it. 4. Too static As I have proved in other threads, I'm not exactly a fan of having tons of Javascript all the time, but I think that some slightly better interaction would be nice, I'll explain this more below. 5. Little-to-no cross referencing Cross module references would be complicated and error-prone, so I don't expect that. However, other than manually placed links, there are no links in the actual documentation proper. There's probably more, but these annoy me the most. Now unfortunately I can't really deal with each point individually for a solution, so I'll try to address all of them in the next section. Ok, so I'm going to say this: I like the Java documentation. There, I said it. Its clean, its functional, finding things is relatively easy, sure it could be improved *cough*frames*cough*, but I like that trying to find things isn't a mission. Anyway, the Java docs have some particular layout features that I really like: * The whole screen is for documentation - This is important because documentation is dense, and any chance to spread it out is great. * Drill down interface - Important for Java because of its tendency to just produce more and more and more classes, but the idea is good nonetheless. * Separation of elements - Again, there's a certain amount of Java-specificness about this, since everything is in a class, and a file can only contain one public class, but it gives a summary of the class at the beginning, breaking it down into methods, methods inherited, fields and constructors before going onto detail after that. While I do not advocate direct copying of the Java style, the ideas are good. I think that a generated summary table at the beginning would be better, probably have a very top-level one that has 4 separate lists: Classes, Structs, Functions and Templates, containing all the module-level declarations in that file. From there, each Top-level declaration is clearly separated from the others, with Class/struct summaries if appropriate, and they are grouped together according to type, and in the order that is presented in the list near the top. This solves three of the problems with the list at the top: easy scanning - a table of categorized data is easier to read than a simple list; ordering - currently the list is ordered in alphabetical order, but the contents is not, meaning that there is a disconnect between the two presentations of the content, and that can get annoying and finally, name duplication - if only top-level declarations are used, then you can have all the names in the list, since you won't have things like opIndex in the list, unless it is actually a top-level function. The separation of the top-level elements (and the inner elements in a class/struct) needs to be done at both ends, you can't signal the end of one item by the beginning of another, since that conflicts with the idea of nested items, just indentation isn't enough to visually indicate ownership, boxes are good, boxes contain things. This isn't code, its presentation. However, all
Re: Documentation Layout
On Wed, Mar 28, 2012 at 12:20 AM, James Miller ja...@aatch.net wrote: In another thread ( http://forum.dlang.org/thread/CAMfGmZsNX3GsOFVyUaCX79E4H8eTBXqDmUJtm41JSzRNtME=r...@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. 1. The Jump To index. This is the worst one for me, hence top of the list, its an inline list of the classes, structs and functions on the page. Actually, technically its a list of all the anchors on the page, with duplicate names removed and then sorted (poorly) and outputted all in a row. While this is manageable for say std.array, its ~4.5 lines on std.string. Some modules have tables at the beginning that replace the index, and this is better (std.algorithm for example) but can become out of date, due to the fact that it is hand-maintained. Yeah, I'm not a fan of the Jump To links. They are often unwieldy and not in any easily discernible order so they are often just clutter. I was toying with the idea of making it only show top level structs, classes, etc and then possibly having yet another Jump To section above each struct/class with nested symbols. I haven't looked into how easy this would be to do yet. 2. No ordering + unobvious separation of elements Due to what I can only assume is the way DDoc generates code, there is no obvious ordering to the page, you can have a class definition followed by its methods followed by a few top-level functions then a struct and its members. Combine this with the fact that all things are styled the same, with indenting for members, you can easily get lost scanning through a class when you suddenly find yourself at a completely different class. Agreed. I'm not sure what can be done about the way ddoc orders things though. As far as I know it's just in the order it appears in the source. I'm not sure how you'd even go about specifying a different ordering from source order (even ignoring ddoc, just speaking of documentation generators in general). 3. No search Ok, there is a search, it is a small box, near the top, that searches either: the entire site, the library reference or the news group. It hands it off to Google and returns a Google search. This isn't very good for user experience, ideally you wouldn't leave the site, it would be internal and use the fact that you are searching documentation to be a bit smarter about it. I've been trying to generate parsable ddoc output for use in an autocomplete for the search box (symbol names + short documentation excerpts for context). I had some luck but couldn't strip it down to the bare minimum information I wanted to extract so I got it in my head that I should try adding documentation to dmd's json output instead. I haven't attempted this yet. I think the search is very important. Right now someone basically has to tell you where which module certain structs/classes are in std.typecons has a lot of useful stuff but nobody would ever think to check there to find out where tuples or RefCounted are. Just yesterday I was very confused about why the documentation for 'recurrence' had gone missing but it turns out it's in std.range, not std.algorithm. 4. Too static As I have proved in other threads, I'm not exactly a fan of having tons of Javascript all the time, but I think that some slightly better interaction would be nice, I'll explain this more below. 5. Little-to-no cross referencing Cross module references would be complicated and error-prone, so I don't expect that. However, other than manually placed links, there are no links in the actual documentation proper. I think this just has to be done manually. There's probably more, but these annoy me the most. Now unfortunately I can't really deal with each point individually for a solution, so I'll try to address all of them in the next section. Ok, so I'm going to say this: I like the Java documentation. There, I said it. Its clean, its functional, finding things is relatively easy, sure it could be improved *cough*frames*cough*, but I like that trying to find things isn't a mission. Anyway, the Java docs have some particular layout features that I really like: * The whole screen is for documentation - This is important because documentation is dense, and any chance to spread it out is great. * Drill down interface - Important for Java because of its tendency to just produce more and more and more classes, but the idea is good nonetheless. * Separation of elements - Again, there's a certain amount of Java-specificness about this, since everything is in a class, and a file can only contain one
Re: Documentation Layout
On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller wrote: 1. The Jump To index. I did a little program called improveddoc that builds nicer tables: http://arsdnet.net/d-web-site/improveddoc.d makes: http://arsdnet.net/d-web-site/std_stdio.html It does post-processing on the dom to build it. We talked a while ago about integrating it into the website build process, but I haven't gotten around to figuring that out yet. 2. No ordering + unobvious separation of elements I believe it is in the same order as the original source code. 3. No search Another thing I started but never finished is http://dpldocs.info/ You can jump to a thing with: http://dpldocs.info/std.stdio.file or search: http://dpldocs.info/file the rest of your post is tl;dr, I'll look at it later though. The problem with my doc stuff is just finding the time to finish off the integration. The basics work pretty well now as you can see at the links above.
Re: Documentation Layout
On Wednesday, 28 March 2012 at 14:47:53 UTC, Adam D. Ruppe wrote: On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller wrote: 1. The Jump To index. I did a little program called improveddoc that builds nicer tables: http://arsdnet.net/d-web-site/improveddoc.d makes: http://arsdnet.net/d-web-site/std_stdio.html It does post-processing on the dom to build it. 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
Re: Documentation Layout
On 3/28/12 2:20 PM, James Miller wrote: Ok, so I'm going to say this: I like the Java documentation. There, I said it. I like it too. http://downloads.dsource.org/projects/descent/ddoc/phobos/ http://downloads.dsource.org/projects/descent/ddoc/tango/ And cross-references are not hard at all. The compiler has everything it needs to know them (it can compile your code, which is way more complex! :-P) Back them when I presented that format (which could be improved, it's still hard to find something on the right pane) there wasn't a lot of interest for it. I think documentation look feel is paramount.
Re: Documentation Layout
On 2012-03-28 19:34, Ary Manzana wrote: On 3/28/12 2:20 PM, James Miller wrote: Ok, so I'm going to say this: I like the Java documentation. There, I said it. I like it too. http://downloads.dsource.org/projects/descent/ddoc/phobos/ http://downloads.dsource.org/projects/descent/ddoc/tango/ And cross-references are not hard at all. The compiler has everything it needs to know them (it can compile your code, which is way more complex! :-P) Back them when I presented that format (which could be improved, it's still hard to find something on the right pane) there wasn't a lot of interest for it. I think documentation look feel is paramount. I think the documentation generated by descent is great, it just need some styling :) -- /Jacob Carlborg
Re: Documentation Layout
On Wednesday, 28 March 2012 at 16:40:19 UTC, Nathan M. Swan wrote: On Wednesday, 28 March 2012 at 14:47:53 UTC, Adam D. Ruppe wrote: On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller wrote: 1. The Jump To index. I did a little program called improveddoc that builds nicer tables: http://arsdnet.net/d-web-site/improveddoc.d makes: http://arsdnet.net/d-web-site/std_stdio.html It does post-processing on the dom to build it. 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 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. D has an advanced module system yet people insist on treating D as if all we have are #includes. When that's coming from the developers of the standard library that looks like a huge warning sign to me. While I applaud Adam's efforts I don't think that what we need is a complex multistage documentation system. The recent posts about Rust peaked my curiosity and I picked at their docs. I was thoroughly impressed by the improvement they made since the last time I looked. The previous time (long ago) I quickly dismissed it but as their developer said himself it really shows that they eat their own dog food and the polish is very apparent. The only think that annoyed me was the ridiculous abbreviation mess - looks like something a teenager on twitter would use. There's really no good reason to shorten return to ret and mutable to mut. in fact, their code shows they started with mutable and then did a search/replace to shorten it. ?!?
Re: Documentation Layout
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).
Re: Documentation Layout
On Wednesday, 28 March 2012 at 07:00:58 UTC, Brad Anderson wrote: [...] I've been trying to generate parsable ddoc output for use in an autocomplete for the search box (symbol names + short documentation excerpts for context). I had some luck but couldn't strip it down to the bare minimum information I wanted to extract so I got it in my head that I should try adding documentation to dmd's json output instead. I haven't attempted this yet. I think the search is very important. Right now someone basically has to tell you where which module certain structs/classes are in std.typecons has a lot of useful stuff but nobody would ever think to check there to find out where tuples or RefCounted are. Just yesterday I was very confused about why the documentation for 'recurrence' had gone missing but it turns out it's in std.range, not std.algorithm. [...] As long as normal documentation output is turned on, my Json improvements (https://github.com/D-Programming-Language/dmd/pull/813) will output the (unformatted) documentation comments associated with all top-level declarations. Take a look at that.
Re: Documentation Layout
On Wed, Mar 28, 2012 at 6:32 PM, Matt Peterson ricoche...@gmail.com wrote: On Wednesday, 28 March 2012 at 07:00:58 UTC, Brad Anderson wrote: [...] I've been trying to generate parsable ddoc output for use in an autocomplete for the search box (symbol names + short documentation excerpts for context). I had some luck but couldn't strip it down to the bare minimum information I wanted to extract so I got it in my head that I should try adding documentation to dmd's json output instead. I haven't attempted this yet. I think the search is very important. Right now someone basically has to tell you where which module certain structs/classes are in std.typecons has a lot of useful stuff but nobody would ever think to check there to find out where tuples or RefCounted are. Just yesterday I was very confused about why the documentation for 'recurrence' had gone missing but it turns out it's in std.range, not std.algorithm. [...] As long as normal documentation output is turned on, my Json improvements ( https://github.com/D-**Programming-Language/dmd/pull/**813https://github.com/D-Programming-Language/dmd/pull/813) will output the (unformatted) documentation comments associated with all top-level declarations. Take a look at that. Oh great. Saves me some trouble. Regards, Brad Anderson
Re: Documentation Layout
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
Re: Documentation Layout
On 29 March 2012 13:58, Nathan M. Swan nathanms...@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
Re: Documentation Layout
On Thu, Mar 29, 2012 at 02:52:17PM +1300, James Miller wrote:
[...]
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.
I would argue code comments should do the same.
This reminds me of when I was working as a teaching assistant in
college. In class, the lecturer drilled it into the students that they
need to comment their code, the more comments the better. So some
students handed in code that looked like this:
// Define a function
int myfunction(int y) {
// Loop from 1 to 10
for (int i=0; i 10; i++) {
int x; // declare a variable
x = i; // set x to 0
// If condition is satisfied
if (x*2 + y*3 - 7 9) {
y--;// decrement y
}
}
// Return result
return y*3 - x;
}
Next class, the lecturer had to tell them that comments are not for
restating what's already obvious from the code; they're intended to
explain what *isn't* obvious, like what's the purpose of the function,
what's the meaning behind the if-condition, etc..
I had my laugh then, but now I'm working in the industry and sometimes I
see code like this:
int somePoorlyNamedFunction(int y) {
int x = 123;
if (y*7 - 4*x + 9 16) {
// Fix bug of wrong result
return 19-x;
}
return 17-y;
}
and I start wondering where people bought their diplomas from...
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.
[...]
Yikes!! I think my next doc-related pull request may very well have to
be std.string... :-/
T
--
No, John. I want formats that are actually useful, rather than
over-featured megaliths that address all questions by piling on
ridiculous internal links in forms which are hideously over-complex. --
Simon St. Laurent on xml-dev
Re: Documentation Layout
On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller wrote: In another thread (http://forum.dlang.org/thread/CAMfGmZsNX3GsOFVyUaCX79E4H8eTBXqDmUJtm41JSzRNtME=r...@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?
Re: Documentation Layout
On 29 March 2012 18:26, Jakob Ovrum jakobov...@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
