Skip to content

Tag Code Refs with D ddoc tag for findSkip Documentation #4002

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
quickfur merged 1 commit into from
Feb 24, 2016
Merged

Tag Code Refs with D ddoc tag for findSkip Documentation #4002

quickfur merged 1 commit into from
Feb 24, 2016
+29 −32

Conversation

@nordlow
Copy link
Contributor

@nordlow nordlow commented Feb 15, 2016

No description provided.

@JakobOvrum
Copy link
Contributor

JakobOvrum commented Feb 15, 2016

Please use the new … syntax instead of $(D …).

@nordlow
Copy link
Contributor Author

nordlow commented Feb 15, 2016

  1. What about references to code in different languages? In the docs for findSkip I refer to Python and Lisp code aswell...
  2. Why not apply this transformation on all cases together?

@JakobOvrum
Copy link
Contributor

JakobOvrum commented Feb 15, 2016

  1. We have CCODE and CPPCODE, but I don't think we have a general "foreign language" macro. Maybe CODE is it, but it currently evaluates to the same as D. I think it's fine to use … for now.
  2. See $(D code) -> code #2877.

@quickfur
Copy link
Member

quickfur commented Feb 15, 2016

Yes, please use ... for code symbols.

@quickfur
Copy link
Member

quickfur commented Feb 22, 2016

ping
Any updates? Just change it to ... and let's merge this.

@nordlow
Copy link
Contributor Author

nordlow commented Feb 23, 2016

Should I fix all the comments for findSplit?

@quickfur
Copy link
Member

quickfur commented Feb 23, 2016

If you want to, sure. But at least, the text that was changed should use the new syntax for $(D ...).

@nordlow
Update searching.d
74deecc 
Tag code with D ddoc tag.
@nordlow
Copy link
Contributor Author

nordlow commented Feb 24, 2016

Done.

@quickfur
Copy link
Member

quickfur commented Feb 24, 2016

Thanks!

@quickfur
Copy link
Member

quickfur commented Feb 24, 2016

Auto-merge toggled on

quickfur pushed a commit that referenced this pull request Feb 24, 2016
Merge pull request #4002 from nordlow/patch-1
5dfa9b2 
Tag Code Refs with D ddoc tag for findSkip Documentation
@quickfur quickfur merged commit 5dfa9b2 into dlang:master Feb 24, 2016
@adamdruppe
Copy link
Contributor

adamdruppe commented Feb 24, 2016

I didn't see this before it was merged, but I'd ask you all to remember that $(D ...) is NOT the same as backticks, so be careful when transforming them.

$(D ...) has the implied semantics of being actual D language code. ddox and my doc generator both apply D syntax highlighting to $(D ...). Notice the word true under the return value on these two pages:

http://dpldocs.info/experimental-docs/std.algorithm.searching.findSkip.html
http://dlang.org/library/std/algorithm/searching/find_skip.html

ddox I believe also uses it as a hint for its cross-referencing system.

My doc gen (not sure about ddox, but it shouldn't either) does NOT apply D syntax highlighting to generic backticks, because it is not necessarily D code. Backticks may enclose code in any language.

$(D ...) in ddoc may also contain other macros, whereas backticks may not. So if you do decide to try an automatic conversion (which I am very much AGAINST), also be sure you scan it for nested macros too. There's several docs in Phobos that use things like $(D $(LREF ...)). Which is IMO foolish, and I'm removing all those in my doc fork, but they do exist upstream.

@dnadlinger
Copy link
Contributor

dnadlinger commented Feb 24, 2016

Backticks may enclose code in any language.

This seems like a questionable claim and/or design decision, given that the vast, vast majority of code snippets in DDoc comments will be D code, and this is arguably also the only case where the improved readability really matters.

@adamdruppe
Copy link
Contributor

adamdruppe commented Feb 24, 2016

The driving reason I wanted the backtick feature was to document my XML library, where the majority of the uses are along the lines of:

/// Given `<tagname class="foo">`, returns `foo`
string className();

Which is something totally unreasonable to do with ddoc before the backticks, because the < and > characters would have to be manually escaped to prevent improper interpretation.

/// Given $(CODE $(LT)tagname class="foo"$(GT)), returns $(CODE foo)
string className();

I can live with CODE, that syntax isn't really bad and $(D ...) is even more concise, but the LT and GT are just too much of a burden to use and this is the specific use case the backticks solved for me.

Using generic backticks for D code might not be ideal because you lack the highlighting and such, but it is not wrong. (I wouldn't change existing $(D) to backticks but when writing new code, I could go either way)

However, on the other hand, if backticks necessarily meant D code and could be interpreted as such by the generators, that would be wrong because it'd leave things like the XML example case out in limbo again. A HTML example where <body> got highlighted as a D keyword would be fairly silly.

@quickfur
Copy link
Member

quickfur commented Feb 24, 2016

TBH, I think $(D ...) and ... should simply be rendered in monospaced font, and no assumptions should be made about what language it's in. I find overuse of colors very distracting and hard to read when it's in the middle of prose. Longer snippets should be in code blocks anyway, where it's pretty safe to assume it's D code.

@nordlow nordlow deleted the patch-1 branch October 19, 2021 19:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@nordlow @JakobOvrum @quickfur @adamdruppe @dnadlinger