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.

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

Relax rules for documentation comments #1820

Closed
hdgarrood opened this issue Jan 11, 2016 · 8 comments
Closed

Relax rules for documentation comments #1820

hdgarrood opened this issue Jan 11, 2016 · 8 comments
Labels
purs docs type: enhancement
Milestone
0.9.0

Comments

@hdgarrood
Copy link
Contributor

Currently, all of the documentation lines before a declaration must begin with a pipe character for those comments to be considered documentation (which determines whether they show up in psc-docs and pursuit).

This means that lots of documentation gets accidentally lost. For instance, slice from arrays:

The documentation disappears because of the preceding "Subarrays" comment.

I propose that instead of requiring every line starts with a pipe, we simply take only those that start with a pipe. I doubt that this would lead to us including anything that people didn't intend to include - I don't consider this change very risky.

See also the relevant source:

purescript/src/Language/PureScript/Docs/Convert.hs

Lines 201 to 218 in a0b92c7

convertComments :: [P.Comment] -> Maybe String
convertComments cs = do
let raw = concatMap toLines cs
guard (all hasPipe raw && not (null raw))
return (go raw)
where
go = unlines . map stripPipes
toLines (P.LineComment s) = [s]
toLines (P.BlockComment s) = lines s
hasPipe s = case dropWhile (== ' ') s of { ('|':_) -> True; _ -> False }
stripPipes = dropPipe . dropWhile (== ' ')
dropPipe ('|':' ':s) = s
dropPipe ('|':s) = s
dropPipe s = s

@hdgarrood
Copy link
Contributor Author

This is super easy to implement, so I can send a PR, but preferably not until #1770 is merged.

@garyb
Copy link
Member

garyb commented Jan 11, 2016

👍!

I thought that's the way it worked already actually (just taking pipe-prefixed lines).

@zudov
Copy link
Contributor

zudov commented Jan 11, 2016

TIL, that every line has to be prefixed with a pipe (not like in haskell, where it's only the first line, and the subsequent pipes would appear in the docs)

@hdgarrood
Copy link
Contributor Author

Hmm, we should probably document this somewhere. Language Guide?

@zudov
Copy link
Contributor

zudov commented Jan 11, 2016

@hdgarrood Differences-from-haskell page also wouldn't hurt. I find it intuitive that every line has to have a pipe, and I thought that it's not the case only because of Haskell knowledge (in Haskell I've ended up with lots of bars in my docstrings a few times)

@hdgarrood
Copy link
Contributor Author

👍

@paf31 paf31 added this to the 0.9.0 milestone Jan 13, 2016
@paf31
Copy link
Contributor

paf31 commented Jan 13, 2016

👍

@garyb garyb closed this as completed in 761106e Jan 16, 2016
garyb added a commit that referenced this issue Jan 16, 2016
@garyb
Merge pull request #1826 from hdgarrood/relax-documentation-comments
14b8aa1 
Relax rules for docs comments, fixes #1820
@hdgarrood
Copy link
Contributor Author

Wiki updated:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
purs docs type: enhancement
Projects
None yet
Milestone
0.9.0
Development

No branches or pull requests
4 participants
@paf31 @garyb @hdgarrood @zudov