Skip to content
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.

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

WIP: Implement 'at-docsyntax' [skip ci]. #12020

Closed

Conversation

MichaelHatherly
Copy link
Member

A rough WIP sketch of the @docsyntax idea @one-more-minute mentioned in #11970.

@docsyntax defines a module constant called __DOCSYNTAX__ that stores that module's format.

@doc then transforms all docstrings into calls to the format specific macro, which can be handled however the macro author chooses.

doc"..." is now only for avoiding interpolation. The markdown parsing is handled by the @doc_markdown macro.

module T

@docsyntax rst

macro doc_rst(text)
    text
end

"..."
f(x) = x

end

@yuyichao
Copy link
Contributor

yuyichao commented Jul 5, 2015

I think specifying the format itself is not the real issue this is trying to solve. Writing rst"<...>" expr really isn't that bad.

This is brought up as an alternative to doc"<...>"rst which is to solve @Keno 's original issue so I think it would be nice to come up with a patch that solve the parsing issue (only allow specific string macros as doc strings) at the same time.

@MichaelHatherly
Copy link
Member Author

@yuyichao this is to move away from needing to special case anything more than plain strings and doc".." in the parser by allowing a user to specify their preferred format using @docsyntax format rather than doc"..."format or format"...".

@yuyichao
Copy link
Contributor

yuyichao commented Jul 5, 2015

I (personally) still think it's necessary to support specifying format for a single doc string even though it would not be very common.

@MichaelHatherly
Copy link
Member Author

By using @doc directly you can get the same effect:

module T

type RST
    text
end

@doc RST("...") ->
f(x) = x

"..."
g(x) = x

end

As you said it's not a very common need to mixed different formats, so using @doc directly in the needed cases should be sufficient?

@yuyichao
Copy link
Contributor

yuyichao commented Jul 5, 2015

As you said it's not a very common need to mixed different formats, so using @doc directly in the needed cases should be sufficient?

I think I can take this.

@MichaelHatherly
Copy link
Member Author

If we could get #11764 then doc".." could also be removed and we'd be left with no excess noise at all, which @hayd has raised valid concerns about.

@yuyichao yuyichao added the docsystem The documentation building system label Jul 6, 2015
@MichaelHatherly MichaelHatherly deleted the mh/atdocsyntax branch August 3, 2015 05:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docsystem The documentation building system
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants