Integrate docfx #1075

nirinchev · 2016-12-28T00:51:26Z

TODO:

~~Add some intro to api/index.md.~~
Logo update.
Decide if we should use PCL/Xamarin project

Consider namespace changes

Realms.ObjectSchema -> Realms.Schema.ObjectSchema
~~Realms.XXXAttribute -> Realms.Attributes.XXXAttribute~~
Realms.XXXException -> Realms.Exceptions.XXXException

Decide what to filter out

IRealmObjectHelper
RealmObject.{Get|Set}XXXValue
WovenAttribute, WovenPropertyAttribute
PreserveAttribute

Functional changes

Removed RealmObjectAlreadyManagedByRealmException.
Made RealmSchema.Builder private.

Resolves #1074
Resolves #854

kristiandupont · 2016-12-28T08:32:16Z

Is docfx_project a standard name? Seems a bit inconsistent with what we otherwise have..

nirinchev · 2016-12-28T11:05:42Z

That's the standard folder you get from running docfx init -q, but I guess I could rename it, I don't think any of the functionality is tied to that name.

nirinchev · 2016-12-28T15:41:24Z

Should we exclude obsolete members from the api reference? Ping @AndyDentFree @fealebenpae @kristiandupont

AndyDentFree · 2016-12-28T15:44:59Z

Should we exclude obsolete members from the api reference?

Good question. I think we keep them.

Whilst code using older NuGets will still compile, they need to be documented as being obsolete. We can't erase outdated code samples floating around the net so it is important that anyone doing a search for those methods will see docs showing their obsolete status and the replacements.

kristiandupont · 2016-12-29T07:16:07Z

The view source links point to the PCL version of the code. It should probably point to the shared version instead.

AndyDentFree · 2016-12-29T07:26:59Z

I'd like to remove the Improve this Doc links. We may need to add hooks to notify us of people posting such improvements and I don't think the team is big enough to manage such an open contribution approach.

AndyDentFree · 2016-12-29T07:35:35Z

Frankly, I don't see the appeal. It has better typography (which can be configured) but loses a number of points of functionality:

poorer navigation
no easy overview
more noise
no search.

kristiandupont

Tiny nits, overall this looks good!

kristiandupont · 2016-12-29T07:18:34Z

Docs/index.md

+Instructions on how to build from source are included in that repository's `README.md`. 
+
+
+Minimal Sample


Perhaps this should be a link to walkthrough docs instead? Seems redundant to maintain another minimal sample with no real added value..

kristiandupont · 2016-12-29T07:25:47Z

Docs/template/partials/footer.tmpl.partial

@@ -0,0 +1,14 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}


I guess this should say Realm Inc instead.

This is the original footer which is licensed by MS, I'm not a lawyer, but I don't think we can copyright it :)

The change is in the footer text - I replace Microsoft with Realm :)

kristiandupont · 2016-12-29T07:26:38Z

Docs/linqsupport.md

+LINQ support in Realm Xamarin
+=============================
+
+To make a query with Realm, you use the `Realm.All<T>()` method to get a `IQueryable<T>` instance. 


All of these should be cref's, but that is probably outside the scope of this PR.

kristiandupont · 2016-12-29T07:31:42Z

Platform.PCL/Realm.PCL/Schema/ObjectSchemaPCL.cs

    /// </summary>
    public class ObjectSchema : IReadOnlyCollection<Property>
    {
        /// <summary>
        /// Gets the name of the original class declaration from which the schema was built.
        /// </summary>
+        /// <value>The name of the class.</value>


Are these necessary? Does lacking them make the docs look incomplete or something? They seem really redundant to me.

kristiandupont · 2016-12-29T07:36:12Z

Shared/Realm.Shared/Extensions/CollectionNotificationsExtensions.cs

@@ -139,12 +142,12 @@ public static class CollectionNotificationsExtensions
        }

        /// <summary>
-        /// A convenience method that casts <c>IQueryable{T}</c> to <see cref="IRealmCollection{T}"/> which implements INotifyCollectionChanged.
+        /// <b>Deprecated</b> A convenience method that casts <see cref="IQueryable{T}"/> to <see cref="IRealmCollection{T}"/> which implements INotifyCollectionChanged.


Doesn't docfx respect the [Obsolete] attribute?

It doesn't display it very prominently.

kristiandupont · 2016-12-29T07:38:44Z

Shared/Realm.Shared/RealmConfigurationBase.cs

+        /// };
+        /// </code>
+        /// </example>
+        /// <value>Typically left null so by default all <see cref="RealmObject"/>s will be able to be stored in all Realms.</value>


This seems inconsistent with what the <value> elements normally contain -- this is more like a remark.

kristiandupont · 2016-12-29T07:44:23Z

Shared/Realm.Shared/exceptions/RealmInvalidTransactionException.cs

@@ -19,7 +19,8 @@
 namespace Realms
 {
    /// <summary>
-    /// An exception, thrown when trying to write data to the Realm and you haven't begun a Write transaction or when the realm is opened as read-only.
+    /// An exception, thrown when trying to write data to the <see cref="Realm"/> and you haven't begun a Write 
+    /// <see cref="Transaction"/> or when the <see cref="Realm"/> is opened as read-only.


Is this the exception that is thrown when trying to create a transaction on a readonly realm? Because if not, I think the case is covered by the comment above. Also, it could be reworded to "when trying to write data the realm outside a transaction" or similar.

kristiandupont · 2016-12-29T07:45:57Z

Shared/Realm.Sync.Shared/Exceptions/HttpException.cs

        public HttpStatusCode StatusCode { get; }

        /// <summary>
        /// Gets the ReasonPhrase of the response.
        /// </summary>
+        /// <value>The ReasonPhrase of the response.</value>


This, as well as the summary, provides very little information about what this actually is. Maybe it could say "HTTP ReasonPhrase" or something?

kristiandupont · 2016-12-29T07:49:30Z

Shared/Realm.Sync.Shared/Exceptions/SessionErrorException.cs

@@ -28,11 +28,13 @@ public class SessionErrorException : Exception
        /// <summary>
        /// Gets the kind of session error this exception represents.
        /// </summary>
+        /// <value>An enum value, describing the root cause of the error.</value>


The "root cause" could be that the sysadmin who was supposed to keep the server running was lazy. I think this merely describes the error :-)

nirinchev · 2016-12-29T11:09:19Z

In terms of appeal, here are a few points:

It's the next iteration of Sandcastle and as such, looks quite similar to sandcastle generated docs (e.g. Newtonsoft.Json).
Most new .NET projects coming from MS use it to drive docs, e.g. Orleans.
It has search (no idea why that hasn't rendered, investigating).
It has a link to the source code so people can easily check what exactly is happening.
It allows plugging in markdown files to supplement the xml docs.
While it has its own set of issues, it correctly recognizes c# 6.0 syntax.
It has links to the BCL classes (INotifyCollectionChanged, etc.).
It shows extension methods in the declaring class - User.GetManagementRealm, Realm.GetSession, etc.
It looks more "modern".

nirinchev · 2016-12-29T14:52:09Z

I deployed the docs on github pages so you can play with it: https://nirinchev.github.io/DocfxTest/index.html

fealebenpae

I like the proposed namespace changes.

Why make RealmSchema.Builder private, though? I know we don't expose the API needed to open a Realm with a wholly dynamic schema, but when we do users'll need it to describe the schema programmatically.

nirinchev · 2016-12-31T01:27:05Z

@fealebenpae I'd say let's keep them private for now (otherwise it's a bit confusing to have them in our public API, but not offer any chance to use them). Once we expose the dynamic opening API, we'll make them public again. How does that sound?

nirinchev · 2016-12-31T02:36:55Z

The reason why "View Source" links to the pcl is that docfx doesn't play nicely with Xamarin projects - it doesn't resolve BCL references. It works fine with the windows project, but we don't have a windows.sync project to generate the sync docs from. So as far as I can see, we have 4 options here:

Generate docs from PCL and have "View Source" point to the dummy implementation for the time being.
Generate docs from Xamarin.iOS/Android and have unresolved BCL references (e.g. INotifyCollectionChanged, IList<T>, etc.). This one is not very appealing, because when we have a BCL reference in the XML docs, it will replace it with an empty string (i.e. not only does it not link to msdn, it also will not show the name of the class, which is quite confusing).
Create a dummy Win32.Sync project just for docs.
Have @fealebenpae ship a working Win32.Sync implementation over the weekend.

Personally, I find Option 4 most appealing, but would be happy to hear your thoughts as well. @kristiandupont @AndyDentFree

nirinchev · 2017-01-02T04:35:02Z

I decided against the attribute namespace change - mainly because I imagine it will be very common scenario to add attributes to your models, which will make it really annoying to have to add both namespaces.

- add reference to msdn nuget - include [EditorBrowsable(Never)] API - add changelog

- Add references on many occasions - Add <value> for properties - Improve wording Move RealmSchema to Realms.Schema namespace Remove RealmObjectAlreadyManagedByRealmException

nirinchev added S:In Progress labels Dec 28, 2016

realm-ci assigned nirinchev Dec 28, 2016

kristiandupont suggested changes Dec 29, 2016

View reviewed changes

fealebenpae reviewed Dec 29, 2016

View reviewed changes

nirinchev added 13 commits January 4, 2017 05:35

init docfx and clean up a little

e749898

Add default template (will be used for further customization)

442a8fe

Filter out some stuff

faf462a

Use template merging instead of creating a complete copy

fc3a68f

Add index.md and linqsupport.md

97cd94d

Fix <code> and <c> blocks

9d8227a

Add Realm footer

3341963

Fix external dependencies

e82a8e7

- add reference to msdn nuget - include [EditorBrowsable(Never)] API - add changelog

Update the readme for nuget restore

e0b6f69

fix the overwrite

2ce5702

move stuff around

50e6e3d

Move docfx to Docs

b3dee64

Fix filterConfig path

0156e57

nirinchev added 12 commits January 4, 2017 05:36

Fix docs

1ebe968

- Add references on many occasions - Add <value> for properties - Improve wording Move RealmSchema to Realms.Schema namespace Remove RealmObjectAlreadyManagedByRealmException

Add <value> docs for sync

2ed6cca

Fix permission link

bcfd418

fix whitespace

3bee89a

Update linqsupport to use Add instead of CreateObject

1198172

Fix spelling

973de55

Address comments

c7ae395

Stylecop typo

2428c1c

Update exception namespaces

840317a

Remove reference/index.md

0d6bcc6

Update the logo

de92fc3

Fix the pcl build

4a7e331

nirinchev force-pushed the ni/docfx branch from 96210bd to 4a7e331 Compare January 4, 2017 03:37

nirinchev mentioned this pull request Jan 4, 2017

Create a "fake" Win32 sync project #1097

Closed

nirinchev added S:Review and removed S:In Progress labels Jan 4, 2017

kristiandupont approved these changes Jan 4, 2017

View reviewed changes

nirinchev merged commit 4546f72 into master Jan 4, 2017

nirinchev deleted the ni/docfx branch January 4, 2017 23:38

nirinchev removed the S:Review label Jan 4, 2017

github-actions bot locked as resolved and limited conversation to collaborators Mar 15, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Integrate docfx #1075

Integrate docfx #1075

nirinchev commented Dec 28, 2016 •

edited

Loading

kristiandupont commented Dec 28, 2016

nirinchev commented Dec 28, 2016

nirinchev commented Dec 28, 2016 •

edited

Loading

AndyDentFree commented Dec 28, 2016

kristiandupont commented Dec 29, 2016

AndyDentFree commented Dec 29, 2016

AndyDentFree commented Dec 29, 2016

kristiandupont left a comment

kristiandupont Dec 29, 2016

kristiandupont Dec 29, 2016

nirinchev Dec 29, 2016

nirinchev Dec 29, 2016

kristiandupont Dec 29, 2016

kristiandupont Dec 29, 2016

nirinchev Dec 29, 2016

kristiandupont Dec 29, 2016

nirinchev Dec 29, 2016

kristiandupont Dec 29, 2016

kristiandupont Dec 29, 2016

kristiandupont Dec 29, 2016

kristiandupont Dec 29, 2016

nirinchev commented Dec 29, 2016

nirinchev commented Dec 29, 2016

fealebenpae left a comment

nirinchev commented Dec 31, 2016

nirinchev commented Dec 31, 2016

nirinchev commented Jan 2, 2017

		Instructions on how to build from source are included in that repository's `README.md`.


		Minimal Sample

		@@ -0,0 +1,14 @@
		{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}

Integrate docfx #1075

Integrate docfx #1075

Conversation

nirinchev commented Dec 28, 2016 • edited Loading

kristiandupont commented Dec 28, 2016

nirinchev commented Dec 28, 2016

nirinchev commented Dec 28, 2016 • edited Loading

AndyDentFree commented Dec 28, 2016

kristiandupont commented Dec 29, 2016

AndyDentFree commented Dec 29, 2016

AndyDentFree commented Dec 29, 2016

kristiandupont left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nirinchev commented Dec 29, 2016

nirinchev commented Dec 29, 2016

fealebenpae left a comment

Choose a reason for hiding this comment

nirinchev commented Dec 31, 2016

nirinchev commented Dec 31, 2016

nirinchev commented Jan 2, 2017

nirinchev commented Dec 28, 2016 •

edited

Loading

nirinchev commented Dec 28, 2016 •

edited

Loading