Docs #3895
Docs #3895
Conversation
std/algorithm/searching.d
Outdated
|
Please try to use more descriptive commit messages; none of the ones you wrote are very informative. |
I assume you mean Is |
|
On Thu, Dec 31, 2015 at 07:23:45PM -0800, Vladimir Panteleev wrote:
No, I don't even know what LNAME is. It doesn't show up in a grep either. Oh there it is, in the druntime changelog... But the one I had in mind was: If an LREF should always be rendered in code font, just make it |
|
Yep, sorry, LREF not LNAME. LREF is short for "local reference"... nothing about its name implies that its contents will be in code font. Do I really need to explain why changing the meaning of macros is bad? |
|
On Thu, Dec 31, 2015 at 07:44:07PM -0800, Vladimir Panteleev wrote:
Then why is it EVER in code font? On one of these pages, every
This isn't the meaning, it seems to just be about a styling issue, |
I don't understand what you mean - clearly the answer is because every instance of it referred to a code identifier. Anyway, I just looked at it (sorry I'm not home right now so I'm limited in doing such research), and didn't realize that LREF was never used on 'dlang.org`, only Phobos and always referring to symbols. However, there are cases like: To avoid regressions in HTML output, we would need to merge PRs introducing the LREF change simultaneously with all PRs in Phobos/Druntime that fix LREF references. It might be easier to do this by introducing a new macro first, then changing content to use that macro, then maybe removing the old macro. This also brings no confusion of what |
|
On Thu, Dec 31, 2015 at 10:36:43PM -0800, Vladimir Panteleev wrote:
That should just be $(LREF GC.BlkAttr.NO_MOVE) because the whole symbol is a local reference. Since DDOC_ANCHOR is defined to put a leading dot in front, LREF should do the same thing, so it continues to work on everything. All those instances should be replaced. It was never actually correct to link to just one part of the name. If a global symbol was ever introduced with the same name, it would break that link!
If it is a regression to add a html class to a link, this process is more broken than I realized.
LREF means "local reference" and since you're documenting code, a local reference also happens to be a code identifier, so the css may style it as one. |
OK, just saying that such instances will need to be updated.
Not sure what process you refer to, but I thought there's more to it than a CSS class. Anyway, I just looked at LREF again and realized that it's already defined as |
|
On Fri, Jan 01, 2016 at 11:59:09AM -0800, Vladimir Panteleev wrote:
Right, I did a grep in Phobos and pushed the commit here too |
|
So I'm continuing to push almost random changes here mostly just so you can see what I've been doing with my fork. Between the pretty blue links in the beautifully formatted navigation bar telling me what I haven't looked at yet and the ease of just editing a file here without spending a lot of brain power on ddoc strangeness (most of this remains compatible but some of it isn't) and just not caring about the auto tester's irrelevant nitpicking, I'm able to make quite a few nice changes. |
|
How do you plan to integrate your work back into upstream Phobos? |
|
(ping) the longer you wait, the more conflicts you might get ;-) |
|
I'm periodically pulling and rebasing to keep my changes up to date. However, there's mixes of ddoc compatible and non-ddoc changes in here now too. |
|
Ah I thought you wanted to merge those typos and better descriptions. My fault :/ Is there an easy way to separate the compatible changes? |
|
On Fri, Mar 04, 2016 at 12:12:34PM -0800, Seb wrote:
I think going through the diff line by line will do it, but I still |
This is also addressed in #3926. |
|
On Wed, Mar 30, 2016 at 01:19:04PM -0700, Seb wrote:
That's why I wrote the MREF macro! |
|
So more than a year went by & apparently no one wanted to merge this big PR. Moreover, thanks to a couple of deprecations (e.g. removal of @adamdruppe I am now closing this with regrets due to inactivity, but I highly encourage you to resubmit this work - maybe split into a PR per module? |
|
On Sun, Dec 25, 2016 at 10:02:48PM -0800, Sebastian Wilzbach wrote:
@adamdruppe I am now closing this with regrets due to inactivity, but I highly encourage you to resubmit this work - maybe split into a PR per module?
I'm doing it all on a private fork now anyway, I decided to just drop compatibility with vanilla ddoc and am no longer attempting to work
with it.
|
5 participants
As I go through building my ddoc killer, I'm noticing a lot of deficiencies in the doc sources, some big, some small.
std.algorithm.searching had a typo, for example, leading to a broken link. std.base64 had a LINK2 title with commas in it, leading to cut off text.
Several of them have LINK2 modules, which breaks anywhere except /phobos (even ddox has these broken links).
Many of the examples don't say what they are trying to do or don't show enough information to actually be useful.
Functions don't refer to each other when they obviously could (obvious to someone who knows Phobos already that is, the new reader would have no idea). In general, browsing Phobos docs, it is easy to lose the forest for the trees. There's few examples of how to integrate modules.
There's an anti-pattern of two macros always appearing together, like
$(M1 $(M2 ...)). That's silly, if M1 should always be applied to M2, just change M2's definition.A great many FAQs in the support arena are not answered in the docs. I am adding a new section called "Diagnostics" with sample compiler error messages and showing how to fix them.
New users go to std.path to see what is in the current path, but that is actually in std.file. Let's have them link to each other.
Some functions create their own
$(RED Important:) ...constructs. I propose changing them to be a well-defined semantic macro like$(PITFALL).In a few places, I also add a blank line. This should be irrelevant to phobos, but it gives my doc generator a natural place to insert a table of contents after a brief introduction. The first line in ddoc is supposed to be a summary. Some functions lack this. Some write it with the assumption that it will be read immediately preceding the rest of the comment, making them read nonsensically if extracted into said table of contents. I reword a few of these.
I rearranged the
toStringzoverloads to put the one with the simpler signature first. Then a user browsing down will see that simple one as the entry point and the other one as an alternative. A small thing that has a bigger source diff than it really is, but makes things a bit more readable for the first-time browser.I have a lot more in store. I'm willing to compromise a little to maintain compatibility with ddoc while still getting content enhancements merged, though my main goal here is to make better docs.