improve docs no-namedparams

2sxc Docs Generator/pages/abyss/releases/history/v17/breaking.md

@@ -7,6 +7,11 @@ uid: Abyss.Releases.History.V17.Breaking
 [!include["Breaking Changes"](./_brc17-planned.md)]
 
 
+TODO:
+
+1. `ToSic.Eav.App.AppData` is renamed to `ToSic.Eav.Apps.DataSources.AppDataWithApi`
+1. `AppState` changes...
+
 ---
 
 Shortlink: <https://go.2sxc.org/brc-17>

2sxc Docs Generator/pages/guides/vscode/index.md

@@ -70,7 +70,10 @@ EndProject
     <Reference Include="..\..\..\..\bin\ToSic.*.dll" />
 
     <!-- also add DotNetNuke DLLs - we don't recommend this, because then your code will never be hybrid -->
-    <!-- <Reference Include="..\..\..\..\bin\DotNetNuke.*.dll" /> -->
+    <!--
+    <Reference Include="..\..\..\..\bin\DotNetNuke.dll" />
+    <Reference Include="..\..\..\..\bin\DotNetNuke.*.dll" />
+    -->
   </ItemGroup>
 
   <!-- Polymorphism

2sxc Docs Generator/pages/net-code/conventions/named-parameters.md

@@ -3,17 +3,55 @@ uid: NetCode.Conventions.NamedParameters
 ---
 # Convention: Named Parameters
 
-When working with the C# / Razor API, most commands require named parameters. This means that a command like this is valid
+When working with the C# / Razor API, _advanced/optional parameters_ must be **named**.
 
-```cs
+> [!TIP]
+> A named parameter is determined by it's name (eg `settings:`),  
+> like `SomeMethod(settings: someValue)`  
+> vs. a positional parameter which is specified by the position in the list of arguments,  
+> like `SomeMethod(someValue)`.
+
+## Example
+
+```razor
+@inherits Custom.Hybrid.RazorTyped
+
+@* this is a command without named parameters - all works *@
+@MyItem.Picture("Packshot")
+
+@* this is a command with named parameters for more advanced settings *@
+@MyItem.Picture("Packshot", settings: "Lightbox")
+
+@* this is a command with named parameters for exact width control *@
+@MyItem.Picture("Packshot", width: 500)
+
+@* An example using both parameters in any order *@
+@MyItem.Picture("Packshot", settings: "Lightbox", width: 500)
+@MyItem.Picture("Packshot", width: 500, settings: "Lightbox")
+```
+
+The previous example shows
+
+1. A Razor inheriting from `Custom.Hybrid.RazorTyped` to enable the new `MyItem.Picture(...)` API
+1. A add-picture with only the basic parameter. This doesn't need the name as the position (first parameter) makes it clear that `Packshot` is the field containing the picture
+1. A more advanced use case where the picture uses `settings: "Lightbox"` (this must be named with `settings: ...`)
+1. Another use case where the picture uses `width: 500` (named with `width: ...`)
+1. Two more examples specifying multiple parameters - showing that the order is not important since we have the names
+
+As you can see in the `settings:` and `width:` example, both of these parameters are on the second position.
+If they were not named, the API wouldn't know if `500` or `Lightbox` was a width, setting or anything else.
+
+## Example using Toolbars
+
+This means that a command like this is valid
+
+```html
+<!-- valid -->
 <div @Edit.TagToolbar(actions: "new", contentType: "BlogPost")>
   ...
 </div>
-```
-
-...and this is not
 
-```cs
+<!-- not valid -->
 <div @Edit.TagToolbar("new", "BlogPost")>
   ...
 </div>

docs/abyss/releases/history/v17/breaking.html

@@ -160,6 +160,12 @@ <h4 id="how-to-fix">How to Fix</h4>
 <pre><code class="lang-c#">var app = App;
 var version = App.Configuration.Get(&quot;Version&quot;);
 </code></pre>
+
+<p>TODO:</p>
+<ol>
+<li><code>ToSic.Eav.App.AppData</code> is renamed to <code>ToSic.Eav.Apps.DataSources.AppDataWithApi</code></li>
+<li><code>AppState</code> changes...</li>
+</ol>
 <hr>
 <p>Shortlink: <a href="https://go.2sxc.org/brc-17">https://go.2sxc.org/brc-17</a></p>
 </article>

docs/api/dot-net/Custom.DataSource.DataSource16.html

@@ -456,18 +456,18 @@ <h5 class="returns">Returns</h5>
   </table>
   <span class="small pull-right mobile-hide">
     <span class="divider">|</span>
-    <a href="https://github.com/2sic/2sxc/new/develop/apiSpec/new?filename=Custom_DataSource_DataSource16_ProvideOut_System_Func_System_Object__System_String_System_String_System_Func_ToSic_Eav_Data_Build_DataFactoryOptions__.md&amp;value=---%0Auid%3A%20Custom.DataSource.DataSource16.ProvideOut(System.Func%7BSystem.Object%7D%2CSystem.String%2CSystem.String%2CSystem.Func%7BToSic.Eav.Data.Build.DataFactoryOptions%7D)%0Asummary%3A%20&#39;*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax&#39;%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A">Improve this Doc</a>
+    <a href="https://github.com/2sic/2sxc/new/develop/apiSpec/new?filename=Custom_DataSource_DataSource16_ProvideOut_System_Func_System_Object__ToSic_Lib_Coding_NoParamOrder_System_String_System_Func_ToSic_Eav_Data_Build_DataFactoryOptions__.md&amp;value=---%0Auid%3A%20Custom.DataSource.DataSource16.ProvideOut(System.Func%7BSystem.Object%7D%2CToSic.Lib.Coding.NoParamOrder%2CSystem.String%2CSystem.Func%7BToSic.Eav.Data.Build.DataFactoryOptions%7D)%0Asummary%3A%20&#39;*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax&#39;%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A">Improve this Doc</a>
   </span>
   <span class="small pull-right mobile-hide">
     <a href="https://github.com/2sic/2sxc/blob/develop/Src/Sxc/ToSic.Sxc/Custom.DataSources/DataSource16.cs/#L62">View Source</a>
   </span>
   <a id="Custom_DataSource_DataSource16_ProvideOut_" data-uid="Custom.DataSource.DataSource16.ProvideOut*"></a>
-  <h4 id="Custom_DataSource_DataSource16_ProvideOut_System_Func_System_Object__System_String_System_String_System_Func_ToSic_Eav_Data_Build_DataFactoryOptions__" data-uid="Custom.DataSource.DataSource16.ProvideOut(System.Func{System.Object},System.String,System.String,System.Func{ToSic.Eav.Data.Build.DataFactoryOptions})">ProvideOut(Func&lt;object&gt;, string, string, Func&lt;DataFactoryOptions&gt;)</h4>
+  <h4 id="Custom_DataSource_DataSource16_ProvideOut_System_Func_System_Object__ToSic_Lib_Coding_NoParamOrder_System_String_System_Func_ToSic_Eav_Data_Build_DataFactoryOptions__" data-uid="Custom.DataSource.DataSource16.ProvideOut(System.Func{System.Object},ToSic.Lib.Coding.NoParamOrder,System.String,System.Func{ToSic.Eav.Data.Build.DataFactoryOptions})">ProvideOut(Func&lt;object&gt;, NoParamOrder, string, Func&lt;DataFactoryOptions&gt;)</h4>
   <div class="markdown level1 summary"></div>
   <div class="markdown level1 conceptual"></div>
   <h5 class="declaration">Declaration</h5>
   <div class="codewrapper">
-    <pre><code class="lang-csharp hljs">protected void ProvideOut(Func&lt;object&gt; getList, string noParamOrder = &quot;Params must be named (https://go.2sxc.org/named-params)&quot;, string name = &quot;Default&quot;, Func&lt;DataFactoryOptions&gt; options = null)</code></pre>
+    <pre><code class="lang-csharp hljs">protected void ProvideOut(Func&lt;object&gt; getList, NoParamOrder noParamOrder = default, string name = &quot;Default&quot;, Func&lt;DataFactoryOptions&gt; options = null)</code></pre>
   </div>
   <h5 class="parameters">Parameters</h5>
   <table class="table table-bordered table-condensed">
@@ -485,7 +485,7 @@ <h5 class="parameters">Parameters</h5>
         <td></td>
       </tr>
       <tr>
-        <td><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></td>
+        <td><a class="xref" href="ToSic.Lib.Coding.NoParamOrder.html">NoParamOrder</a></td>
         <td><span class="parametername">noParamOrder</span></td>
         <td></td>
       </tr>
@@ -672,7 +672,7 @@ <h3 id="implements">Implements</h3>
                     <a href="https://github.com/2sic/2sxc/new/develop/apiSpec/new?filename=Custom_DataSource_DataSource16.md&amp;value=---%0Auid%3A%20Custom.DataSource.DataSource16%0Asummary%3A%20&#39;*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax&#39;%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A" class="contribution-link">Improve this Doc</a>
                   </li>
                   <li>
-                    <a href="https://github.com/2sic/2sxc/blob/develop/Src/Sxc/ToSic.Sxc/Custom.DataSources/DataSources16_IDataSourceExplicit.cs/#L12" class="contribution-link">View Source</a>
+                    <a href="https://github.com/2sic/2sxc/blob/develop/Src/Sxc/ToSic.Sxc/Custom.DataSources/DataSources16_IDataSourceExplicit.cs/#L13" class="contribution-link">View Source</a>
                   </li>
                 </ul>
               </div>

docs/api/dot-net/Custom.Dnn.Api12.html

@@ -224,13 +224,13 @@ <h5>Inherited Members</h5>
       <a class="xref" href="Custom.Hybrid.Api12.html#Custom_Hybrid_Api12_AsAdam_ToSic_Eav_Data_ICanBeEntity_System_String_">Api12.AsAdam(ICanBeEntity, string)</a>
     </div>
     <div>
-      <a class="xref" href="Custom.Hybrid.Api12.html#Custom_Hybrid_Api12_SaveInAdam_System_String_System_IO_Stream_System_String_System_String_System_Nullable_System_Guid__System_String_System_String_">Api12.SaveInAdam(string, Stream, string, string, Guid?, string, string)</a>
+      <a class="xref" href="Custom.Hybrid.Api12.html#Custom_Hybrid_Api12_SaveInAdam_ToSic_Lib_Coding_NoParamOrder_System_IO_Stream_System_String_System_String_System_Nullable_System_Guid__System_String_System_String_">Api12.SaveInAdam(NoParamOrder, Stream, string, string, Guid?, string, string)</a>
     </div>
     <div>
-      <a class="xref" href="Custom.Hybrid.Api12.html#Custom_Hybrid_Api12_CreateInstance_System_String_System_String_System_String_System_String_System_Boolean_">Api12.CreateInstance(string, string, string, string, bool)</a>
+      <a class="xref" href="Custom.Hybrid.Api12.html#Custom_Hybrid_Api12_CreateInstance_System_String_ToSic_Lib_Coding_NoParamOrder_System_String_System_String_System_Boolean_">Api12.CreateInstance(string, NoParamOrder, string, string, bool)</a>
     </div>
     <div>
-      <a class="xref" href="Custom.Hybrid.Api12.html#Custom_Hybrid_Api12_File_System_String_System_Nullable_System_Boolean__System_String_System_String_System_String_System_Object_">Api12.File(string, bool?, string, string, string, object)</a>
+      <a class="xref" href="Custom.Hybrid.Api12.html#Custom_Hybrid_Api12_File_ToSic_Lib_Coding_NoParamOrder_System_Nullable_System_Boolean__System_String_System_String_System_String_System_Object_">Api12.File(NoParamOrder, bool?, string, string, string, object)</a>
     </div>
     <div>
       <a class="xref" href="Custom.Hybrid.Api12.html#Custom_Hybrid_Api12_Ok">Api12.Ok()</a>

docs/api/dot-net/Custom.Dnn.Code12.html

@@ -191,7 +191,7 @@ <h5>Inherited Members</h5>
       <a class="xref" href="ToSic.Sxc.Code.DynamicCode12.html#ToSic_Sxc_Code_DynamicCode12_Edit">DynamicCode12.Edit</a>
     </div>
     <div>
-      <a class="xref" href="ToSic.Sxc.Code.DynamicCode12.html#ToSic_Sxc_Code_DynamicCode12_CreateInstance_System_String_System_String_System_String_System_String_System_Boolean_">DynamicCode12.CreateInstance(string, string, string, string, bool)</a>
+      <a class="xref" href="ToSic.Sxc.Code.DynamicCode12.html#ToSic_Sxc_Code_DynamicCode12_CreateInstance_System_String_ToSic_Lib_Coding_NoParamOrder_System_String_System_String_System_Boolean_">DynamicCode12.CreateInstance(string, NoParamOrder, string, string, bool)</a>
     </div>
     <div>
       <a class="xref" href="ToSic.Sxc.Code.DynamicCode12.html#ToSic_Sxc_Code_DynamicCode12_CmsContext">DynamicCode12.CmsContext</a>

docs/api/dot-net/Custom.Dnn.Razor12.html

@@ -224,7 +224,7 @@ <h5>Inherited Members</h5>
       <a class="xref" href="Custom.Hybrid.Razor12.html#Custom_Hybrid_Razor12_Settings">Razor12.Settings</a>
     </div>
     <div>
-      <a class="xref" href="Custom.Hybrid.Razor12.html#Custom_Hybrid_Razor12_CreateInstance_System_String_System_String_System_String_System_String_System_Boolean_">Razor12.CreateInstance(string, string, string, string, bool)</a>
+      <a class="xref" href="Custom.Hybrid.Razor12.html#Custom_Hybrid_Razor12_CreateInstance_System_String_ToSic_Lib_Coding_NoParamOrder_System_String_System_String_System_Boolean_">Razor12.CreateInstance(string, NoParamOrder, string, string, bool)</a>
     </div>
     <div>
       <a class="xref" href="Custom.Hybrid.Razor12.html#Custom_Hybrid_Razor12_DynamicModel">Razor12.DynamicModel</a>