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

Documentation should include version numbers #261

Closed
GoogleCodeExporter opened this Issue Mar 15, 2015 · 5 comments

Comments

Projects
None yet
2 participants
@GoogleCodeExporter

GoogleCodeExporter commented Mar 15, 2015

We should be able to include "Introduced in 1.1.0" or whatever in version 
numbers, for the autogenerated documentation.

It shouldn't be too hard to do this as part of the AnnotationDocumenter tool. 
(We don't actually need annotations, but it's similar "XML documentation 
post-processing".)

This should be automatic based on previous XML documentation files.

Unfortunately as far as I can see, there's no specific XML tag for this. I've 
raised https://shfb.codeplex.com/discussions/476990 to ask for advice.

Original issue reported on code.google.com by jonathan.skeet on 24 Dec 2013 at 12:28

@GoogleCodeExporter

This comment has been minimized.

GoogleCodeExporter commented Mar 15, 2015

I looked into this for the 1.1.0 release.  The Version Builder SHFB plugin was 
the only premade thing I could find, but it didn't really seem appropriate (you 
wouldn't be able to build the documentation without a bunch of .DLLs lying 
around).

A <since> tag in the source would make more sense.  Would we just make it 
freeform text (so that we could write "Since: 1.1, not available in the PCL 
version"), or would we encode the "1.1" and "not PCL" parts separately, perhaps?

Original comment by malcolm.rowe on 26 Dec 2013 at 7:34

@GoogleCodeExporter

This comment has been minimized.

GoogleCodeExporter commented Mar 15, 2015

I think it would make sense to encode them separately, and autogenerate both. 
I'm not immediately sure how I'd determine that something wasn't available in 
the PCL version just from the XML; I think I'd need the PCL DLL itself. For the 
moment we might be best to autogenerate the "since" part and just do the 
not-PCL bit manually. (If we make it an *attribute* in the XML, we could 
validate it with unit tests... but that does seem a bit silly in some ways.)

It's the XSLT part which I'm most likely to need a hand with, to be honest.

Original comment by jonathan.skeet on 26 Dec 2013 at 7:42

@GoogleCodeExporter

This comment has been minimized.

GoogleCodeExporter commented Mar 15, 2015

Fixed in 4bcd8537331a. This changes the API documentation style to a variation 
of VS2010, but it was simpler to do that in a single change than to split it.

It's all somewhat hacky - we create a custom style on the fly - but it works...

Original comment by jonathan.skeet on 2 Jan 2014 at 2:23

@GoogleCodeExporter

This comment has been minimized.

GoogleCodeExporter commented Mar 15, 2015

Slightly annoyingly, the VS2010 presentation style goes straight to the 
NodaTime namespace when you visit http://nodatime.org/unstable/api, but we may 
be able to handle that separately. (Also, it doesn't load in quite the same way 
in incognito mode in Chrome, for some reason.)

Original comment by jonathan.skeet on 2 Jan 2014 at 3:34

  • Changed state: Fixed
@GoogleCodeExporter

This comment has been minimized.

GoogleCodeExporter commented Mar 15, 2015

Original comment by malcolm.rowe on 22 Jun 2014 at 12:15

  • Added labels: Milestone-1.3.0
  • Removed labels: Milestone-1.3-consider

@malcolmr malcolmr modified the milestone: 1.3.0 Mar 15, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment